supercode_harness/

config.rs

use std::collections::HashMap;
use std::path::PathBuf;

use supercode_runtime::EventSink;

pub(crate) use supercode_runtime::glob_match;
pub use supercode_runtime::CachePlan;

/// The default OpenRouter base URL. Any OpenAI-compatible endpoint works too.
pub const OPENROUTER_BASE_URL: &str = "https://openrouter.ai/api/v1";

/// Environment variable consulted for the API key when none is set explicitly.
pub const DEFAULT_API_KEY_ENV: &str = "OPENROUTER_API_KEY";

/// Built-in prompt templates (slash commands), e.g. `/code-review`.
fn default_prompts() -> std::collections::HashMap<String, String> {
    let mut m = std::collections::HashMap::new();
    m.insert(
        "code-review".to_string(),
        "Review the current code changes for correctness bugs, then for \
reuse/simplification/efficiency cleanups. {args}\nUse the available tools to \
inspect the diff and files. Report findings grouped by severity."
            .to_string(),
    );
    m
}

/// A default, deliberately small system prompt. Override it freely.
pub const DEFAULT_SYSTEM_PROMPT: &str = "\
You are supercode, a precise and efficient AI coding agent operating in a user's \
working directory. Use the available tools to inspect and modify files and run \
commands. Prefer reading before writing. Make minimal, correct changes and explain \
what you did concisely.";

/// When the agent must seek approval before running a tool — the analog of
/// Codex's `-a untrusted|on-request|never` and Claude's permission modes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ApprovalPolicy {
    /// Never ask — every tool call runs automatically (default).
    #[default]
    Never,
    /// Ask for tools not on the auto-approve allowlist.
    OnRequest,
    /// Ask for every tool call.
    Untrusted,
    /// P5-1 (COMPOSABLE-HARNESS-DESIGN.md §3.2 S8, §4.3 cx-parity): Codex's
    /// `-a on-request` default — escalation is INITIATED BY THE MODEL, not
    /// decided by a client-side allowlist check the way [`Self::OnRequest`]
    /// is (`Config::needs_approval`'s `OnRequest` arm consults
    /// `Config::auto_approved_tools`/`tool_allow_patterns`; Codex's
    /// `on-request` instead runs sandboxed writes/reads silently and only
    /// asks when the MODEL itself requests to leave the sandbox —
    /// `protocol.rs:921-924`). Using [`Self::OnRequest`] for cx-parity would
    /// prompt on every non-allowlisted call, where stock Codex prompts
    /// almost never — a materially different (over-prompting, but not
    /// unsafe) posture, which is why `configfile::parse_approval_str`
    /// previously fell back to [`Self::Untrusted`] rather than silently
    /// picking the wrong existing variant (S8's original fail-safe). This
    /// variant now exists so cx-parity resolves to its INTENDED posture
    /// instead of that fail-safe. `Config::needs_approval` (the coarse,
    /// tool-name-only legacy gate — no model-escalation signal reaches it)
    /// treats this conservatively, the same as [`Self::OnRequest`]; the P5-1
    /// permissions engine (`crate::permissions`, the richer canonicalized-
    /// command-aware gate `crate::agent::Agent` consults when
    /// `Config::permissions_enabled` is on) treats it per Codex's real
    /// posture — see that gate's doc comment.
    ModelRequested,
}

/// A callback consulted when a tool call needs approval. Returns `true` to allow.
pub type ApprovalHandler = Box<dyn Fn(&supercode_interchange::ToolCall) -> bool + Send + Sync>;

/// BP-10 (catalog row "Hook/plugin permission veto", semantics
/// "Programmatic allow/deny/**rewrite** before the user sees it"): what a
/// pre-tool hook decided about one call.
///
/// The three non-`Pass` values are TIERS OF THE ONE PERMISSIONS ENGINE, not
/// a second gate beside it — `crate::agent::Agent`'s
/// `permissions_gate_denial_impl` folds this in and the engine's own
/// deny→ask→allow priority decides. In particular [`Self::Allow`] answers
/// an `Ask` on the user's behalf (CC's `PermissionRequest`-class reply) but
/// can never override a `deny` rule: a hard floor stays a hard floor.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum HookDecision {
    /// The hook expressed no opinion — the engine decides alone. The
    /// default, and what a silent (exit-0, no output) hook means.
    #[default]
    Pass,
    /// Answer an `Ask` on the user's behalf: the call proceeds WITHOUT a
    /// prompt, unless a `deny` rule (or a protected path) already refused
    /// it, in which case the refusal stands.
    Allow,
    /// Force the call to the `Ask` tier even if the rules would have
    /// allowed it — "let the user see this one".
    Ask,
    /// Refuse the call outright.
    Deny,
}

/// BP-10: everything a pre-tool hook can say about one call — a decision,
/// a human-readable reason, and (the rewrite half of the row) REPLACEMENT
/// arguments.
#[derive(Debug, Clone, Default)]
pub struct PreToolOutcome {
    /// The hook's verdict — see [`HookDecision`].
    pub decision: HookDecision,
    /// Why, in words. Fed back to the model on a denial; carried to the
    /// approval door otherwise.
    pub reason: Option<String>,
    /// BP-10 (the "rewrite" half): arguments to run the tool with INSTEAD
    /// of the model's own. `None` (the default) leaves the call untouched.
    /// The rewritten arguments are what the permissions engine then
    /// evaluates and what the tool finally receives — a hook cannot
    /// launder a denied command by rewriting it past the gate, because the
    /// gate runs on the REWRITTEN args.
    pub updated_args: Option<serde_json::Value>,
}

impl PreToolOutcome {
    /// No opinion — the pre-BP-10 `None` return.
    pub fn pass() -> Self {
        PreToolOutcome::default()
    }

    /// Refuse the call — the pre-BP-10 `Some(reason)` return.
    pub fn deny(reason: impl Into<String>) -> Self {
        PreToolOutcome {
            decision: HookDecision::Deny,
            reason: Some(reason.into()),
            updated_args: None,
        }
    }

    /// Answer an `Ask` on the user's behalf.
    pub fn allow(reason: Option<String>) -> Self {
        PreToolOutcome {
            decision: HookDecision::Allow,
            reason,
            updated_args: None,
        }
    }

    /// Force the call to the `Ask` tier.
    pub fn ask(reason: Option<String>) -> Self {
        PreToolOutcome {
            decision: HookDecision::Ask,
            reason,
            updated_args: None,
        }
    }

    /// Run the tool with `args` instead of the model's own.
    pub fn rewrite(args: serde_json::Value) -> Self {
        PreToolOutcome {
            decision: HookDecision::Pass,
            reason: None,
            updated_args: Some(args),
        }
    }
}

/// A pre-tool hook: receives the tool name and parsed arguments before
/// execution, and returns a [`PreToolOutcome`] — allow, deny, ask, and/or a
/// rewrite of the arguments. BP-10 widened this from the earlier
/// `Option<String>` ("`Some(reason)` blocks"): the deny half is
/// [`PreToolOutcome::deny`], and the three new answers are what the catalog
/// row's "programmatic allow/deny/rewrite" and CC's `PermissionRequest`
/// hooks actually need.
pub type PreToolHook = Box<dyn Fn(&str, &serde_json::Value) -> PreToolOutcome + Send + Sync>;

/// A post-tool hook: receives the tool name, its output, and whether it errored,
/// after execution (observational — logging, metrics, side effects).
pub type PostToolHook = Box<dyn Fn(&str, &str, bool) + Send + Sync>;

/// A loop lifecycle moment an embedder may observe (BP-11, catalog
/// "Lifecycle hooks, config-registered"): the compaction and subagent
/// boundaries the CLI's `pre_compact`/`post_compact`/`subagent_start`/
/// `subagent_stop` hook events are fired from. Observational only — a
/// lifecycle hook can never veto the moment it observes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LifecycleEvent {
    /// The live window is about to be compacted: `dropped` messages in
    /// `[first, cut)` collapse into one marker; `manual` is a `/compact`.
    PreCompact {
        /// Messages in the window before compaction.
        messages: usize,
        /// Messages about to be collapsed into the marker.
        dropped: usize,
        /// `true` for `/compact`, `false` for an automatic trigger.
        manual: bool,
    },
    /// Compaction finished; the window now holds `messages` entries.
    PostCompact {
        /// Messages in the window after compaction.
        messages: usize,
        /// Messages that were collapsed.
        dropped: usize,
    },
    /// A `spawn_subagent` call passed validation and is about to run.
    SubagentStart {
        /// The task text the child was given.
        task: String,
    },
    /// The `spawn_subagent` call returned (`is_error` is the tool result's flag).
    SubagentStop {
        /// The task text the child was given.
        task: String,
        /// Whether the child's result was an error.
        is_error: bool,
        /// Byte length of the result handed back to the parent.
        output_len: usize,
    },
}

/// A lifecycle observer: receives every [`LifecycleEvent`] (observational).
pub type LifecycleHook = Box<dyn Fn(&LifecycleEvent) + Send + Sync>;

/// How tools are advertised to the model (B6, D16).
///
/// `Full` sends every enabled tool's schema on every request (today's
/// behavior). `Deferred` advertises only a `core` allowlist plus a synthetic
/// `tool_search` meta-tool; everything else — the MCP surface above all,
/// since `McpTool::from_client` eagerly wraps every remote tool with its full
/// `input_schema` — is discoverable via `tool_search` and only advertised
/// (on the *next* request) once activated.
#[derive(Debug, Clone, Default)]
pub enum ToolAdvertising {
    /// All enabled tools every request (today's behavior).
    #[default]
    Full,
    /// Only `core` tools + the `tool_search` meta-tool; everything else is
    /// discoverable via `tool_search` and advertised only after activation.
    Deferred {
        /// Tool names advertised eagerly on every request.
        core: Vec<String>,
    },
}

/// Optional-policy gates resolved from `[capabilities.reduction]`.
///
/// `None` preserves [`crate::reduce::ReductionPolicy`]'s established
/// default for callers that use reduced mode without the composable module
/// surface. A preset or direct capability setting supplies only the gates it
/// names; the CLI applies them when it constructs the live policy.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ReductionPolicySettings {
    pub stale_reads: Option<bool>,
    pub diff_reads: Option<bool>,
    pub duplicates: Option<bool>,
    pub tool_input_elision: Option<bool>,
    pub supersede: Option<bool>,
    pub normalize_output: Option<bool>,
    pub image_redaction: Option<bool>,
    pub span_summaries: Option<bool>,
}

/// Per-tool customization: enable/disable a tool and/or override the description
/// the model sees for it.
#[derive(Debug, Clone, Default)]
pub struct ToolOverride {
    /// If `Some(false)`, the tool is hidden from the model entirely.
    pub enabled: Option<bool>,
    /// If `Some`, replaces the tool's built-in description in the schema.
    pub description: Option<String>,
    /// If `Some`, overrides [`Config::tool_schema_tier`] (TR-8/T5) for this
    /// specific tool — e.g. keep one fat MCP tool at `Full` while the global
    /// knob shrinks everything else to `Minimal`.
    pub schema_tier: Option<crate::tools::SchemaTier>,
    /// P4e (design §3.1/§S14 `core.tools.bash.timeout_secs`): the DEFAULT
    /// execution timeout (seconds) for the `bash` tool when a model-issued
    /// call doesn't supply its own `timeout_ms` argument — see
    /// `tools::builtins::BashTool::execute`'s precedence (an explicit
    /// per-call `timeout_ms` always wins; this only replaces the BUILT-IN
    /// `DEFAULT_BASH_TIMEOUT_MS` fallback). Only meaningful on the `bash`
    /// entry; other tools ignore it. `None` (the default) is byte-identical
    /// to today's behavior — `BashTool`'s internal 120s default stands.
    pub timeout_secs: Option<u64>,
}

/// Everything that shapes an [`crate::Agent`]: the model and endpoint, the
/// credentials, sampling parameters, the system prompt, and per-tool overrides.
///
/// Build one with [`Config::builder`].
#[non_exhaustive]
pub struct Config {
    /// Model identifier as understood by the endpoint, e.g.
    /// `anthropic/claude-opus-4-8` or `openai/gpt-5` on OpenRouter.
    pub model: String,

    /// Base URL of the OpenAI-compatible endpoint (no trailing `/chat/...`).
    pub base_url: String,

    /// Explicit API key. If `None`, [`Self::api_key_env`] is consulted.
    pub api_key: Option<String>,

    /// Environment variable to read the API key from when [`Self::api_key`] is unset.
    pub api_key_env: String,

    /// P4 (COMPOSABLE-HARNESS-DESIGN.md §5.2 "P4", §1.8/§3.1
    /// `core.api_key_cmd`, D6 row): a credential-helper command (pi§6
    /// `!command` form). Consulted by `Agent::new` when [`Self::api_key`]
    /// is unset: the command is run through the shell, its trimmed stdout
    /// becomes the key, and a non-zero exit or empty output falls through to
    /// [`Self::api_key_env`] rather than failing outright. `None` (the
    /// default) means this is never consulted — byte-identical to today's
    /// behavior. SECURITY: this is a command string, never a secret value —
    /// [`Self::api_key`] itself must never be file-plaintext (§3.2 S13);
    /// `api_key_cmd` is `[project-forbidden]` at every config-file layer
    /// (§3.3), same trust boundary as `base_url`/`api_key_env`.
    pub api_key_cmd: Option<String>,

    /// BP-9 (§3.1 `core.api_key_command`, D6 row "Credential helpers /
    /// keyring", cc§6 `apiKeyHelper`, cx§6 `auth{command}`): an ARGV
    /// credential helper, exec'd directly (no shell), whose trimmed stdout
    /// becomes the key. Consulted by `Agent::new` BEFORE
    /// [`Self::api_key_cmd`] — it is the safer of the two forms (no
    /// word-splitting, no `$(…)`), so a config that sets both gets the one
    /// with fewer ways to surprise its author. Same fall-through posture as
    /// `api_key_cmd`: a failing/empty helper moves on to the next source
    /// rather than erroring. `None` (the default) is never consulted.
    /// `[project-forbidden]` (§3.3).
    pub api_key_command: Option<Vec<String>>,

    /// BP-9 (§3.1 `core.update_check`, D6 row "Auto-update + channels",
    /// cx§10): whether a startup release check is performed. `false` (the
    /// default) means no startup network access at all — see
    /// `CoreSection::update_check` for why opt-in is the only defensible
    /// default here.
    pub update_check: bool,

    /// System prompt prepended to every conversation.
    pub system_prompt: String,

    /// Optional sampling temperature.
    pub temperature: Option<f32>,

    /// Optional output token cap.
    pub max_tokens: Option<u32>,

    /// Maximum number of model/tool iterations per [`crate::Agent::send`] call.
    pub max_iterations: usize,

    /// Reasoning/effort level sent to the model (`reasoning_effort`).
    pub effort: Option<String>,

    /// Structured-output constraint (`response_format`), e.g. a json_schema.
    pub response_format: Option<serde_json::Value>,

    /// Extra request-body fields merged in (provider-native passthrough:
    /// prompt-cache controls, provider-specific knobs).
    pub extra_body: serde_json::Map<String, serde_json::Value>,

    /// Optional cap on cumulative output tokens across one [`crate::Agent::send`]
    /// loop; the loop stops once exceeded. Output tokens only; input/prompt
    /// tokens are not counted, so this is not a cost cap.
    pub max_total_output_tokens: Option<u64>,

    /// BP-7 (catalog §4a "Turn/budget caps", cc's `--max-budget-usd`): cap
    /// on the cumulative DOLLAR cost of one [`crate::Agent::send`] loop.
    /// The loop stops spawning further model turns once the accumulated
    /// per-turn cost reaches this figure.
    ///
    /// Arming this against a model [`crate::pricing::resolve`] cannot price
    /// is refused at [`crate::Agent::new`] rather than accepted and
    /// silently ignored — a spend cap that cannot bite is worse than none,
    /// because the caller believes they are protected. Set
    /// [`Self::price_input_per_mtok`]/[`Self::price_output_per_mtok`] to
    /// price an unknown model.
    pub max_budget_usd: Option<f64>,

    /// BP-7 (catalog §4a "Turn/budget caps" — the STEP cap the semantics
    /// name alongside turns, spend and output tokens): cap on the number of
    /// TOOL CALLS executed across one [`crate::Agent::send`] loop.
    ///
    /// Distinct from [`Self::max_iterations`], which bounds model
    /// round-trips: one round-trip can carry a whole batch of parallel
    /// tool calls, so a step cap and a turn cap bound different things.
    pub max_steps: Option<usize>,

    /// BP-7: dollars per million INPUT tokens for [`Self::model`],
    /// overriding [`crate::pricing`]'s built-in table. Only takes effect
    /// together with [`Self::price_output_per_mtok`] — half an override
    /// would bill completions at zero.
    pub price_input_per_mtok: Option<f64>,

    /// BP-7: dollars per million OUTPUT tokens for [`Self::model`].
    pub price_output_per_mtok: Option<f64>,

    /// Max bytes of a single tool result fed back into the conversation. Output
    /// beyond this is truncated with a notice, so one runaway command (a huge
    /// log, a binary dump) can't explode the context window. `None` disables the
    /// cap. Defaults to 100 KB.
    pub max_tool_output_bytes: Option<usize>,

    /// BP-2 (§3.1 `core.tool_output_spill`, catalog:58 "Oversized output
    /// truncated; full content kept reachable"): when `true`, an output
    /// capped by [`Self::max_tool_output_bytes`] is first written IN FULL
    /// to a per-session spill file, and the cap notice names that path so
    /// the model can read it back with an ordinary read (`read_file`, or
    /// `cat` under a shell-only preset) — CC's own "Bash overflow → session
    /// file" recovery door, available without `capabilities.reduction`.
    /// `false` (the default) protects an embedder that never asked for
    /// disk writes: the cap notice stays exactly as it is today and no
    /// spill file is created. Both parity presets turn it on.
    pub tool_output_spill: bool,

    /// Working directory tools operate within.
    pub cwd: PathBuf,

    /// Additional roots beyond `cwd` (the analog of `--add-dir` / multi-root):
    /// searched for project-context files and available to tools.
    pub additional_dirs: Vec<PathBuf>,

    /// Whether to auto-load `CLAUDE.md` / `AGENTS.md` into the system prompt.
    pub load_project_context: bool,

    /// Filesystem confinement applied to write-capable tools.
    pub sandbox: crate::tools::SandboxPolicy,

    /// When the agent must seek approval before running a tool.
    pub approval: ApprovalPolicy,

    /// Tools that never require approval under [`ApprovalPolicy::OnRequest`].
    pub auto_approved_tools: std::collections::HashSet<String>,

    /// P4 (design §5.2 "P4": "deny-rule patterns generalizing
    /// auto_approved_tools" — the S-sized generalization, NOT the full P5
    /// `capabilities.permissions.rules` deny→ask→allow engine, §2.1
    /// dependency 3's command-canonicalization prerequisite is P5-only).
    /// Glob patterns (`*` wildcard, see [`glob_match`]) matched against a
    /// tool's NAME — no argument/command-level matching. Any match forces
    /// [`Config::needs_approval`] to `true` UNCONDITIONALLY, even under
    /// [`ApprovalPolicy::Never`] — the entire point of a deny rule is a
    /// hard floor `--yes`/`Never` can't bypass. Sourced from
    /// `capabilities.permissions.rules.deny` (§3.1 module 11); empty by
    /// default (today's behavior, byte-identical).
    pub tool_deny_patterns: Vec<String>,

    /// P4: the ALLOW-pattern generalization of [`Self::auto_approved_tools`]
    /// — glob patterns matched against a tool's NAME, exempting a match from
    /// approval under [`ApprovalPolicy::OnRequest`] exactly like an exact
    /// `auto_approved_tools` entry does (never consulted under `Untrusted`,
    /// same as `auto_approved_tools`). Sourced from
    /// `capabilities.permissions.rules.allow`; empty by default.
    pub tool_allow_patterns: Vec<String>,

    /// Consulted when a tool call needs approval; `None` denies by default.
    pub approval_handler: Option<ApprovalHandler>,

    /// Runs before each tool executes; may block the call.
    pub pre_tool_hook: Option<PreToolHook>,

    /// Runs after each tool executes (observational).
    pub post_tool_hook: Option<PostToolHook>,

    /// Observes compaction and subagent lifecycle moments (observational).
    pub lifecycle_hook: Option<LifecycleHook>,

    /// Named prompt templates (skills / slash commands). A user message of the
    /// form `/<name> <args>` is expanded to the template with `{args}` filled.
    pub prompts: HashMap<String, String>,

    /// If set, the conversation is compacted once it grows beyond this many
    /// messages (older middle turns are summarized into one marker), keeping the
    /// system prompt and the most recent turns.
    pub compact_after_messages: Option<usize>,

    /// Per-tool enable/disable + description overrides, keyed by tool name.
    pub tool_overrides: HashMap<String, ToolOverride>,

    /// How tools are advertised to the model (B6). Defaults to [`ToolAdvertising::Full`].
    pub tool_advertising: ToolAdvertising,

    /// Extra HTTP headers sent with every request (e.g. OpenRouter's
    /// `HTTP-Referer` / `X-Title` attribution headers).
    pub extra_headers: HashMap<String, String>,

    /// Optional sink for streaming [`crate::AgentEvent`]s.
    pub event_sink: Option<EventSink>,

    /// Prompt-caching plan (B7). Defaults to [`CachePlan::Off`]; reduced mode
    /// (`--reduced`, D5/D14) defaults it to [`CachePlan::ImportedPrefix`]
    /// (wired at the CLI's reduced-mode assembly point, `crates/cli/src/main.rs`).
    pub cache_plan: CachePlan,

    /// Resolved optional reduction gates. These are kept separate from the
    /// live policy because freshness probes and prepared summaries are
    /// per-request data, not configuration.
    pub reduction_policy: ReductionPolicySettings,

    /// Whether the explicit reversible handoff projection is available.
    /// This is separate from [`Self::reduction_policy`] because handoff is
    /// an offline command over an existing sidecar, not a per-request
    /// projection pass. Defaults to `true`; only an explicit composable
    /// `capabilities.reduction.handoff = false` disables it.
    pub handoff_enabled: bool,

    /// Global tool-schema tier (TR-8/T5): how verbose ADVERTISED tool
    /// schemas are. Defaults to [`crate::tools::SchemaTier::Full`] (today's
    /// behavior — byte-identical schemas). A per-tool override in
    /// [`ToolOverride::schema_tier`] wins over this for that tool. Tool
    /// definitions are config, never session content, so this never affects
    /// what's stored or exported — only what's advertised on the wire.
    pub tool_schema_tier: crate::tools::SchemaTier,

    /// UX-26 (B7-warn): whether [`crate::Agent`] emits
    /// [`crate::AgentEvent::CacheWarning`] when a turn under
    /// [`CachePlan::ImportedPrefix`] likely paid a full-price prompt-cache
    /// miss despite reuse being expected (idle past the provider's TTL, or
    /// usage reporting a near-zero cache-read ratio). Defaults to `true`
    /// (on-brand token-economics feedback, on by default like the savings
    /// figures `inspect stats` already surfaces); the CLI's
    /// `--no-cache-warnings` flag / `cache_warnings = false` config / the
    /// `SUPERCODE_CACHE_WARNINGS=0` env var turn it off. A no-op — never
    /// checked — for any caller not using `CachePlan::ImportedPrefix`, so
    /// this changes nothing under `CachePlan::Off` (today's default outside
    /// reduced mode).
    pub cache_warnings: bool,

    /// P3 (COMPOSABLE-HARNESS-DESIGN.md §5.2 phase P3, mandatory risk-2
    /// mitigation, §5.3 risk 2): the `[experimental] module_registry` flag.
    /// `false` (the default) means [`crate::tools::ToolRegistry::from_config`]
    /// returns EXACTLY [`crate::tools::ToolRegistry::with_builtins`] — the
    /// runtime path is byte-for-byte today's behavior. Only when explicitly
    /// turned on does [`Self::module_activation`] start shaping the
    /// registry/prompt assembly.
    pub module_registry: bool,

    /// P3: the resolved §2 module-activation set (pure config → set,
    /// computed by [`crate::configfile::resolve`]/[`crate::modules::ModuleActivation::from_harness`]
    /// with no agent loop required). Only consulted when
    /// [`Self::module_registry`] is `true`.
    pub module_activation: crate::modules::ModuleActivation,

    /// P3: the effective `[core.tools] enabled` list (§3.1) — which of the
    /// core four (`read_file`/`bash`/`edit_file`/`write_file`, plus any
    /// future core tool name) are present at all. Defaults to the §1.2
    /// default-active four, matching [`crate::tools::ToolRegistry::with_builtins`]'s
    /// unconditional registration. Only consulted when
    /// [`Self::module_registry`] is `true`.
    pub core_tools_enabled: Vec<String>,

    /// P3: `[core.skills].enabled` (§1.4 obligation 4, D-7) — whether the
    /// skills prompt section may appear at all. Still gated by D-7's read
    /// pathway (`read_file` or `bash` present in [`Self::core_tools_enabled`])
    /// at the assembly site. Only consulted when [`Self::module_registry`]
    /// is `true`.
    pub skills_enabled: bool,

    /// BP-6 (`[core.skills].harness`, catalog D7 "Skill discovery from
    /// multiple roots"): whose documented skill-root table the LOOP reads
    /// SKILL.md packages from — a [`crate::HarnessId`] spelling
    /// (`claude-code`, `codex`, `opencode`, `pi`, …), resolved by
    /// [`crate::skills::skill_roots`]. `None` (the default) means the loop
    /// discovers no packages at all and [`Self::skills_enabled`] can only
    /// index `[core.prompts]` templates, exactly as before BP-6. Only
    /// consulted when [`Self::module_registry`] is `true`.
    pub skills_harness: Option<String>,

    /// BP-6 (`[core.skills].dirs`): extra skill roots, merged OVER the
    /// harness's own defaults — i.e. they win a name collision, since a
    /// root a config names explicitly is more specific than a discovered
    /// one. Scanned as `project` scope.
    pub skills_dirs: Vec<std::path::PathBuf>,

    /// BP-6 (`[core.skills].implicit_match`, cx§7 "implicit
    /// (description-matched) invocation"): whether a user message that
    /// merely DESCRIBES a skill loads its body, in addition to the explicit
    /// `$slug` mention. `false` (the default) is the safe posture: only an
    /// explicit mention, `/name`, or a `skill` tool call ever spends a
    /// body's tokens.
    pub skills_implicit_match: bool,

    /// BP-5 (`[core.skills].shell_injection`, cc§7 "Dynamic context
    /// injection", `docs:skills#inject-dynamic-context`): whether
    /// `` !`cmd` `` (and the ```` ```! ```` block form) inside a skill or
    /// command body is EXECUTED when the body is loaded, its stdout
    /// replacing the token. `false` (the default) leaves the token as
    /// literal text — Claude Code's own `disableSkillShellExecution`
    /// posture, stated positively.
    ///
    /// Never an unconditional shell: every extracted command is evaluated
    /// through the ONE permissions engine ([`crate::permissions`]) with
    /// this config's own rules, protected paths and approval default, plus
    /// whatever the body's `allowed-tools` frontmatter pre-approves for
    /// itself (cc§7 "pre-approved tools while active"). Anything short of
    /// [`crate::permissions::Decision::Allow`] is refused in place, with
    /// the reason inlined where the output would have gone.
    pub skills_shell_injection: bool,

    /// BP-5 (`[core.file_mentions]`, catalog D2 "@-file mentions /
    /// attachments", cc§2 "`@`-file mentions", cx§2 "`@`-mentions
    /// (files)"): whether an `@path` token in a user prompt is expanded
    /// into that file's contents before the turn is sent. `false` (the
    /// default) leaves `@path` as literal text.
    ///
    /// Deny-rule aware (cc§2: "Read deny rules best-effort apply to
    /// `@file` mentions"): each mention is resolved through the same
    /// permissions engine a `read_file` call goes through, so a mention of
    /// a protected path is refused in place rather than silently inlined.
    pub file_mentions: bool,

    /// BP-5 (`[core.output_style]`, catalog D2 "Output style / personality
    /// module", cc§7 "Output styles", cx§2 "Personality layer"): the NAME
    /// of the response-style layer this session runs under — a built-in
    /// ([`crate::output_style::BUILTIN_STYLES`]) or a markdown file
    /// discovered from the style roots of the harness
    /// [`Self::skills_harness`] names. Empty (the default) appends
    /// nothing.
    ///
    /// A style is a prompt-assembly INPUT, not a module with state: it
    /// contributes one section to the system prompt at construction, and
    /// nothing else in the loop consults it.
    pub output_style: String,

    /// BP-5 (`[core.path_rules]`, catalog D2 "Path-scoped rules", cc§2
    /// "`.claude/rules/*.md`"): whether `<root>/.claude/rules/*.md` rule
    /// files are loaded. A rule file with no `paths:` frontmatter joins the
    /// instruction blob at construction; one WITH `paths:` is held back and
    /// injected only when a tool touches a file matching one of its globs
    /// (the same on-demand door `core.nested_instructions` uses).
    /// `false` (the default) reads no rule directory at all.
    pub path_rules: bool,

    /// BP-5 (`[capabilities.model_catalog].base_prompts`, catalog D2
    /// "Per-model-family base-prompt selection", cx§2 "Per-model base
    /// instructions"): model-id GLOB → the base system prompt that family
    /// gets, replacing [`Self::system_prompt`] when it matches.
    ///
    /// The most SPECIFIC match wins (longest pattern), so the table is
    /// order-independent — a TOML table has no order to rely on. No match
    /// (and an empty table, the default) leaves `system_prompt` exactly as
    /// it was, so this is a no-op for every config that doesn't set it.
    /// Re-selected on [`crate::Agent::set_model`], the way cx re-selects
    /// `base_instructions` when the model changes.
    pub model_family_prompts: std::collections::BTreeMap<String, String>,

    /// P4 (COMPOSABLE-HARNESS-DESIGN.md §5.2 "P4", §3.1
    /// `capabilities.model_catalog.small_model`, catalog §4a "Small/utility
    /// model routing knob"): a cheaper/faster model id a caller (e.g. a
    /// [`crate::reduce::summarize::SpanSummarizer`] implementation, or an
    /// auto-title side-call) MAY use instead of [`Self::model`] for
    /// low-stakes side-calls. `None` (the default) means every such
    /// consumer falls back to the main model — the exact §2.1 D-9 fallback
    /// behavior — since nothing in this crate resolves this field on its
    /// own; it is a knob a caller reads, not a routing loop this crate runs.
    pub small_model: Option<String>,

    /// P4 (§3.1 `capabilities.model_catalog.fallback`, catalog §4a "Model
    /// aliases + failure fallback chain"): an ordered list of full model
    /// slugs a caller MAY retry against, in order, if [`Self::model`] fails.
    /// Empty (the default) means no fallback chain is configured. Like
    /// [`Self::small_model`], this is the resolved TABLE only — see
    /// [`crate::model_catalog`]'s module doc for the scope boundary between
    /// "a resolved list of slugs" (this field, S-sized) and an actual
    /// retry/failover loop that consumes it (BP-13's
    /// `Agent::run_loop` fallback pass, which consumes exactly this list).
    pub model_fallback: Vec<String>,

    /// BP-13 (catalog Domain 9): the resolved MODEL-ROUTING table —
    /// aliases (including patterns and provider/account scopes), per-model
    /// effort levels, thinking budgets, service tiers, tool-shape
    /// capability bits, and the config-layer allow/deny lists. Every
    /// routing decision in the product asks this one value:
    /// [`crate::Agent`]'s request build (effort, budget, tier), its
    /// fallback pass, [`crate::tools::ToolRegistry::from_config`]'s
    /// write-surface selection, and the CLI's `--model`/`/model` alias
    /// expansion. Default-empty, which resolves exactly like the built-in
    /// alias table alone did before this field existed.
    pub model_routing: crate::model_catalog::Routing,

    /// BP-13 (catalog D9 "Fast mode / service tiers"): a session-level
    /// service-tier override — what `/fast` sets. It WINS over the
    /// per-model `[capabilities.model_catalog] service_tier` rule, because
    /// it is the live toggle the user just pulled; `None` (the default)
    /// leaves the configured rule in force, and if there is no rule either
    /// the request carries no `service_tier` field at all.
    pub service_tier: Option<String>,

    /// P4b (COMPOSABLE-HARNESS-DESIGN.md design doc S5.2 "P4", S1.4/S3.1
    /// `core.env_context`, catalog S4a "Environment context block
    /// injection"): when `true`, `Agent::with_parts` appends a short
    /// `# Environment` block (cwd, platform, date, best-effort git branch)
    /// to the system prompt, alongside `Self::load_project_context`'s
    /// instruction files. `false` (the default) is byte-identical to
    /// today's behavior.
    pub env_context: bool,

    /// P4b (S1.4/S3.1 `core.project_root_markers`, catalog:232): filenames
    /// (or directory names) that mark a directory as the project root.
    /// Defaults to `[".git"]`.
    ///
    /// BP-9 gave this knob its reader: [`project_root_for`] is the single
    /// shared ancestor walk every consumer goes through — the
    /// `Self::env_context` git-status probe (which now reports the ROOT's
    /// branch, not a subdirectory's), the CLI's `.supercode.toml`
    /// discovery walk (which stops at the root instead of climbing to `/`),
    /// and (BP-4) prompt assembly's instruction walk, whose climb from
    /// `Self::cwd` ends at the first directory carrying one of these
    /// (`agent::instruction_walk_roots`) — cx's own `project_root_markers`
    /// semantics (cx§2). Adding a marker
    /// (`project_root_markers = [".git", ".hg", "package.json"]`) therefore
    /// changes where all of them stop, which is the catalog's semantics
    /// ("configurable markers defining the project root").
    pub project_root_markers: Vec<String>,

    /// P4b (S1.4/S3.1 `core.project_doc_max_bytes`, cx2 "project_doc_max_bytes"
    /// analog, S5.2 P4 "instruction-walk nuances"): a hygiene cap on
    /// instruction-file content (`Self::load_project_context`'s global +
    /// project tiers) appended to the system prompt. `None` (the default) is
    /// uncapped -- byte-identical to today's behavior; only an explicit
    /// `Some(n)` truncates (with a trailing notice), mirroring
    /// `Self::max_tool_output_bytes`'s cap-with-notice shape. BP-4: the cap
    /// binds TWICE -- per FILE (no single instruction file may consume the
    /// whole budget and starve the nearer files that win precedence by
    /// coming after it) and then over the assembled AGGREGATE, which is the
    /// total-bytes reading cx documents (default 32 KiB).
    pub project_doc_max_bytes: Option<usize>,

    /// BP-4 (catalog:87 "Instruction-file hygiene controls", cc2
    /// `claudeMdExcludes`): glob/absolute-path patterns naming instruction
    /// files to SKIP (monorepo hygiene). A pattern is matched against the
    /// file's bare name, its full path, and its path relative to the tier
    /// root it was discovered under. Empty (the default) excludes nothing.
    pub project_doc_excludes: Vec<String>,

    /// BP-4 (catalog:87, cc2 "HTML comment stripping"): when `true`,
    /// block-level `<!-- ... -->` spans are dropped from every instruction
    /// file before injection, so maintainer notes cost no tokens. `false`
    /// (the default, and what cx does -- Codex strips nothing) is
    /// byte-identical to today's behavior.
    pub project_doc_strip_comments: bool,

    /// P4b (S1.4/S3.1 `core.instruction_imports`, catalog:85): when `true`,
    /// an instruction file may reference another file via an `@relative/path`
    /// token (CC's import syntax) -- the referenced file's contents are
    /// inlined in its place, resolved relative to the IMPORTING file's own
    /// directory, to a max depth of 4 (CC's own default) to bound cycles.
    /// `false` (the default) leaves `@` tokens as plain literal text --
    /// byte-identical to today's behavior.
    pub instruction_imports: bool,

    /// P4b (S1.1/S3.1 `core.retry`, pi3 shape): whether a transient
    /// (connection failure / 5xx) provider error is retried at all. This
    /// EXTENDS a pre-existing, always-on transport-layer mechanism
    /// (`provider::OpenAiProvider`'s internal `HttpOptions` retry — 2
    /// attempts / 500ms base backoff, hardcoded, not previously
    /// config-file-settable) rather than adding a second one: `true` (the
    /// default, matching today's always-on behavior byte-for-byte when
    /// `Self::retry_max_retries`/`Self::retry_base_delay_ms` are also both
    /// unset) keeps retrying; an explicit `false` is a NEW capability —
    /// disabling the transport retry entirely.
    pub retry_enabled: bool,
    /// Override the transport retry's attempt count. `None` (the default)
    /// keeps the pre-existing built-in default (2).
    pub retry_max_retries: Option<u32>,
    /// Override the transport retry's base backoff delay in milliseconds
    /// (doubles per attempt). `None` (the default) keeps the pre-existing
    /// built-in default (500ms).
    pub retry_base_delay_ms: Option<u64>,

    /// P4b (S1.5/S3.1 `core.compaction.reserve_tokens`, pi2 shape): once
    /// set, `Agent::maybe_compact` ALSO triggers when the estimated token
    /// size of the live history is within `reserve_tokens` of the model's
    /// context window -- in addition to (not instead of)
    /// `Self::compact_after_messages`'s message-count trigger. `None` (the
    /// default) leaves the pressure trigger off -- byte-identical to today's
    /// message-count-only behavior.
    pub compaction_reserve_tokens: Option<u64>,
    /// P4b (S1.5/S3.1 `core.compaction.keep_recent_tokens`): when the
    /// PRESSURE trigger (not the message-count one) fires, how many of the
    /// most recent tokens (estimated) to keep verbatim instead of a fixed
    /// message count. Only consulted when `Self::compaction_reserve_tokens`
    /// is `Some` and the pressure trigger is what fired.
    pub compaction_keep_recent_tokens: Option<u64>,
    /// P4b (S1.5/S3.1 `core.compaction.focus_instructions`, catalog D2 "no
    /// instruction steering" gap): free text appended to the synthetic
    /// compaction marker message every time compaction fires (either
    /// trigger), steering the model on what to keep focusing on
    /// post-compaction (CC's manual-compact `/compact <focus>` analog).
    /// `None` (the default) leaves the marker text byte-identical to
    /// today's.
    pub compaction_focus_instructions: Option<String>,

    /// P4b (S1.6/S3.1 `core.session.auto_title`, catalog:150, D-9): whether
    /// `crate::session_title::auto_title` may be invoked at all by a caller
    /// (the caller still supplies the `SessionTitler` side-call itself --
    /// this is only the gate, mirroring `Self::small_model`'s "a knob a
    /// caller reads" framing). `false` (the default): callers should treat
    /// auto-title as off.
    pub auto_title: bool,

    /// P4b (S1.7/S3.1 `core.steering`, pi3 semantics): how queued mid-turn
    /// steering messages (`Agent::queue_steer`) are drained -- `All`
    /// delivers every queued message at once, `OneAtATime` (the default)
    /// delivers one per drain point.
    pub steering_mode: SteeringMode,
    /// P4b (S1.7/S3.1 `core.steering.follow_up_mode`): how queued follow-up
    /// messages (`Agent::queue_follow_up`) are drained once the loop is
    /// otherwise idle (no more tool calls pending).
    pub follow_up_mode: SteeringMode,

    /// P4b (S1.9/S3.1 `[core] stop_gate`, D3 "stop/completion gating", CC
    /// Stop-hook semantics cc3): consulted exactly once per `run_loop`
    /// iteration that would otherwise return a final answer (no more tool
    /// calls pending, and the follow-up queue is empty). Receives the
    /// would-be-final assistant message; `Some(reason)` VETOES termination
    /// -- `reason` is injected as a new user message and the loop continues
    /// (still bounded by `Self::max_iterations`); `None` allows the stop.
    /// Code-only, like `Self::pre_tool_hook`/`Self::post_tool_hook` --
    /// the CLI's declarative `[hooks] stop = "cmd"` form (module 17)
    /// populates this SAME single slot rather than adding a second call
    /// site, so the two can never double-fire (S2 module 17's "hooks layer
    /// on core's gate" note). `None` (the default) is byte-identical to
    /// today's behavior.
    pub stop_gate: Option<StopGateHook>,

    /// P4c (COMPOSABLE-HARNESS-DESIGN.md S1.2/S3.1 `core.tools.read_file
    /// multimodal`, catalog S4a "Multimodal read (image passthrough on
    /// `read_file`)"): when `true`, `read_file` returns a recognized image
    /// file (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`/`.bmp`) as a model-visible
    /// image content block instead of decoding it as (garbled) UTF-8 text.
    /// `false` (the default) is byte-identical to today's behavior.
    pub read_file_multimodal: bool,

    /// BP-2 (S1.2/S3.1 `core.tools.read_file.line_numbers`, catalog:26
    /// "Dedicated read with offset/limit, `cat -n` style output"): when
    /// `true`, every line `read_file` returns carries a right-aligned
    /// 1-based line number and a tab, numbered from the requested `offset`
    /// so the model can cite real file line numbers. `false` (the default)
    /// is byte-identical to today's raw-slice behavior -- the harnesses
    /// whose presets do NOT number lines (Codex reads through `cat`) must
    /// keep the unnumbered output their models were trained on.
    pub read_file_line_numbers: bool,

    /// P4c (S1.2/S3.1 `core.tools.edit_file.require_read_before_edit`,
    /// UNIQUE CC row, catalog:32): when `true`, `edit_file` refuses unless
    /// the target path was read (via `read_file`) earlier in this same
    /// conversation -- tracked in `ToolContext`. `false` (the default) is
    /// byte-identical to today's behavior.
    pub edit_file_require_read_before_edit: bool,

    /// P4c (S1.2/S3.1 `core.tools.edit_file.notebook_aware`, UNIQUE CC row
    /// "NotebookEdit", catalog:40): when `true`, `edit_file` additionally
    /// accepts Jupyter cell replace/insert/delete operations against a
    /// `.ipynb` target (see `tools::builtins::EditFileTool`'s cell-op args)
    /// instead of only the exact-string replace it always supports. `false`
    /// (the default) is byte-identical to today's behavior.
    pub edit_file_notebook_aware: bool,

    /// P4c (S1.2/S3.1 `core.shell_env_snapshot`, SPLIT CC+CX row,
    /// catalog:338): when `true`, `Agent::new`/`with_parts` captures the
    /// user's interactive login-shell environment ONCE at construction
    /// (`$SHELL -lc env`, best-effort) and every `bash` call inherits it
    /// directly instead of needing to re-source shell rc files per call.
    /// `false` (the default) is byte-identical to today's behavior -- no
    /// snapshot is captured, and `bash` sees only the ambient process
    /// environment, exactly as before this landed.
    pub shell_env_snapshot: bool,

    /// P4c (S5.2 P4 "doom-loop breaker", oc `doom_loop` UNIQUE row,
    /// catalog D3): when `Some(n)` with `n >= 2`, a tool call whose name AND
    /// arguments are byte-identical to the previous `n - 1` consecutive
    /// calls is refused (fed back to the model as an error) instead of
    /// executed -- the counter resets the moment a call differs. `None`
    /// (the default) is byte-identical to today's behavior: no repetition
    /// tracking, no call is ever refused on this basis.
    pub doom_loop_threshold: Option<u32>,

    /// P4c (S1.4/S3.1 `core.nested_instructions`, catalog:84, deferred from
    /// P4b): when `true`, a `read_file`/`edit_file` call that touches a path
    /// inside a subdirectory carrying its OWN `CLAUDE.md`/`AGENTS.md` (a
    /// directory other than `Config.cwd` itself, which
    /// `Self::load_project_context` already loads once at session start)
    /// appends that subdirectory's instructions to the tool's OWN result the
    /// FIRST time a path under it is touched this conversation (deduped
    /// thereafter -- tracked in `ToolContext`, mirrors CC/OC's "auto-attach
    /// on read, deduped" semantics, catalog:84). Reuses the same
    /// canonicalize+containment safety check P4b's `@`-import expansion
    /// uses (`agent::import_target_is_contained`) so a symlink cannot walk
    /// the injection outside `Config.cwd`. `false` (the default) is
    /// byte-identical to today's behavior.
    pub nested_instructions: bool,

    /// P4c (S1.10/S3.1 `core.model_switch.allow_switch`, D9 row, dep 8):
    /// gates whether `Agent::switch_model` does more than the pre-existing
    /// `Agent::set_model` mechanics (design's "UX-30 dev/02" -- swap
    /// `Config.model` for the next request, nothing else touched). `false`
    /// (the default) makes `switch_model` byte-identical to calling
    /// `set_model` directly: no persisted `model_change` record, no
    /// reasoning-artifact filtering. `true` additionally (1) appends a
    /// typed `model_change::ModelChangeRecord` to
    /// `Agent::model_change_records`, and (2) runs
    /// `reduce::rehydrate::filter_reasoning_artifacts` over `Agent::history`
    /// so model-A's reasoning/thinking artifacts (`ChatMessage::metadata`
    /// keys and any `content_parts` reasoning blocks) never reach
    /// model-B's context (S1.13, dep 8).
    pub model_switch_allow_switch: bool,

    /// BP-13 (§3.1 `core.model_switch.notice`, D9 "Mid-session model
    /// switching"): when the model changes mid-session, splice a short
    /// user-role notice naming the old and new model (and, for an automatic
    /// fallback hop, the failure that caused it) into the live
    /// conversation, so the incoming model reads the handoff rather than
    /// inferring it from a style break. This is Codex's behavior (cx§9
    /// "switch instructions injected"); Claude Code switches silently, so
    /// `false` (the default) is byte-identical to pre-BP-13 behavior and
    /// each preset states which harness it imitates.
    pub model_switch_notice: bool,

    /// BP-13 (§3.1 `capabilities.plan_mode.effort`, catalog D9 "Reasoning
    /// effort / thinking budgets" — the plan-mode half): the reasoning
    /// effort to send WHILE plan mode is active. Codex's `/plan` is
    /// effort-tier steering (cx§6), so planning and executing are not
    /// obliged to think at the same level. `None` (the default) leaves plan
    /// mode with no effort of its own, byte-identical to pre-BP-13
    /// behaviour. Applied by `Agent::apply_routing`, which asks the live
    /// `PlanModeState` — so it turns itself on and off with the mode, and
    /// is still clamped by whatever effort cap applies.
    pub plan_mode_effort: Option<String>,

    /// P4e (§1.4/§3.1 `core.context_injections`, catalog:91 "Synthetic
    /// context-injection blocks"): the master gate for
    /// [`Self::context_injection_blocks`] -- when `false` (the default),
    /// `Agent::with_parts` never appends any of them, byte-identical to
    /// today's behavior. `true` splices in whatever named blocks are set,
    /// at the same assembly site P4b's `env_context` block uses, right
    /// after it.
    pub context_injections: bool,
    /// P4e: named ambient context blocks a caller/embedder populates
    /// programmatically (mirrors `Self::prompts`/`Self::stop_gate`'s
    /// code-extensible shape) -- there is no `[core.context_injections.*]`
    /// FILE table because the §3.1 schema's `core.context_injections` key
    /// is already a scalar boolean gate, and TOML forbids a key being both
    /// scalar and table (the same S-fix documented on
    /// `[core.model_switch]`). Consulted only when
    /// [`Self::context_injections`] is `true`; empty (the default) is a
    /// no-op even then. Each block is appended verbatim as `\n\n# {name}\n{content}`,
    /// in list order.
    pub context_injection_blocks: Vec<ContextInjectionBlock>,

    /// P4e (§1.5/§3.1 `core.compaction.enabled`, "no master gate exists
    /// yet"): the master on/off switch for ALL auto-compaction
    /// (`Agent::maybe_compact`), composing with -- not replacing -- the
    /// existing `Self::compact_after_messages`/`Self::compaction_reserve_tokens`/
    /// `Self::compaction_keep_recent_tokens` triggers: `false` disables
    /// every trigger unconditionally; `true` (the default, matching
    /// today's behavior, where nothing has ever gated compaction) changes
    /// nothing -- whichever triggers are configured still fire exactly as
    /// before.
    pub compaction_enabled: bool,

    /// BP-1 (§1.5/§3.1 `core.compaction.summarize`): whether a compacted
    /// span is replaced by a marker that states it was SUMMARIZED, or by
    /// one that only states it was cleared. `true` (the default, and what
    /// every built-in preset sets) is today's marker text, byte-identical.
    /// Scope note, so this key cannot be over-read: the model-written
    /// summary side-call itself is `capabilities.reduction.span_summaries`'
    /// installed `SpanSummarizer` (D-9, `Agent::set_span_summarizer`) and
    /// is NOT armed by this key -- `core.compaction.summarize` is the
    /// core-compaction statement about what the compaction marker claims,
    /// which is exactly what `Agent::maybe_compact` writes.
    pub compaction_summarize: bool,

    /// P4e (§3.1 `core.parallel_tool_calls`, catalog:59 "Independent
    /// sibling calls run concurrently"): when `true` and an assistant turn
    /// requests more than one tool call, `Agent::run_loop` runs their
    /// `Tool::execute` futures CONCURRENTLY via `Self::run_tools_concurrently`
    /// instead of one at a time -- see that method's doc comment for
    /// exactly which part of dispatch stays strictly sequential (approval /
    /// doom-loop / pre-tool-hook checks, and every `record`/`history`
    /// append, which the lossless sidecar's append-order invariant, S1.13,
    /// requires to stay deterministic). `false` (the default) is
    /// byte-identical to today's sequential-await-per-call loop.
    pub parallel_tool_calls: bool,

    /// P4e (§1.6/§3.1 `core.session.git_metadata`, catalog:331 "Git branch/
    /// sha captured … closes the loop" -- the WRITE half; supercode already
    /// preserves a foreign session's own `gitBranch`-shaped fields
    /// verbatim on IMPORT via `Session::raw`'s byte-for-byte capture).
    /// When `true`, `Agent::with_parts` captures a
    /// `git_metadata::GitMetadataRecord` (best-effort branch/sha/dirty,
    /// like `Self::env_context`'s git probe) once at construction, readable
    /// via `Agent::git_metadata` and persistable via
    /// `Agent::save_git_metadata`. `false` (the default) is byte-identical
    /// to today's behavior: no capture, `Agent::git_metadata()` is always
    /// `None`.
    pub session_git_metadata: bool,

    /// P4e (§1.6/§3.1 `core.session.dir`): overrides the session store's
    /// root directory. A caller-read knob (like `Self::small_model`) --
    /// the CLI's `session_store()` (main.rs) is the consumer. `None` (the
    /// default) leaves the CLI's own default (`$SUPERCODE_HOME/sessions`)
    /// untouched.
    pub session_dir: Option<String>,
    /// P4e (§1.6/§3.1 `core.session.persist`, D5 row): whether a caller
    /// should persist this session to the store at all. A caller-read gate
    /// only -- `Agent`/`Config` never call `SessionStore` directly (no
    /// `SessionStore` handle lives on `Config`); a caller checks this
    /// field directly before calling `store.save(...)`, the same
    /// "mechanism vs. gate" split `Self::auto_title` established. `true`
    /// (the default) matches today's behavior: every caller that already
    /// calls `store.save(...)` keeps doing so unconditionally.
    pub session_persist: bool,
    /// P4e (§1.6/§3.1 `core.session.name`): an explicit session name a
    /// caller should use instead of auto-minting one (the CLI's
    /// `mint_session_name`). A caller-read knob, same posture as
    /// `Self::session_dir`. `None` (the default) leaves auto-naming
    /// untouched.
    pub session_name: Option<String>,
    /// P4e (§1.6/§3.1 `core.session.retention_days`): the archive-pruning
    /// window `store::SessionStore::prune_expired` consults. `None` (the
    /// default) means "never prune" -- byte-identical to today's behavior
    /// (nothing ever prunes automatically).
    pub session_retention_days: Option<u32>,
    /// P4e (§1.6/§3.1 `core.session.export_format`, catalog:283 "transcript
    /// export for humans"): `text` | `html`, consumed by
    /// `human_export::render_transcript`. Defaults to
    /// [`crate::human_export::HumanExportFormat::Text`].
    pub session_export_format: crate::human_export::HumanExportFormat,
    /// BP-8 (§3.1 `core.session.append_only`, catalog:150 "Append-only
    /// durable transcript"): whether the caller arms a
    /// `crate::session_journal::SessionJournal` on this agent, so every
    /// message is written and FLUSHED the instant it exists rather than at
    /// the end of the turn. A caller-read gate, the same "mechanism vs.
    /// gate" split `Self::session_persist` established — `Agent` owns the
    /// journal once one is installed (`Agent::set_journal`), but never
    /// opens a store itself. `false` (the default) is byte-identical to
    /// pre-BP-8 behavior: no journal file is ever created.
    pub session_append_only: bool,
    /// BP-8 (§3.1 `core.session.queue_persist`, catalog:154
    /// "Queued-prompt persistence"): whether pending steering / follow-up
    /// inputs are recorded in the journal as queue operations, so a
    /// prompt typed while the agent was busy survives a crash or restart.
    /// Meaningless without [`Self::session_append_only`] (the journal is
    /// the only place a queue operation is written). `false` (the default)
    /// is byte-identical to pre-BP-8 behavior: both queues stay purely
    /// in-memory.
    pub session_queue_persist: bool,
    /// BP-8 (§2 module `todos` `persist`, catalog:156 "Todos/plan persisted
    /// per session"): whether the `update_plan` checklist is written to the
    /// session store (and restored on resume) rather than living only in
    /// the tool's own mutex for the lifetime of the process. `false` (the
    /// default) is byte-identical to pre-BP-8 behavior.
    pub todos_persist: bool,

    /// P5-1 (§3.1 `capabilities.permissions.enabled`, module 10/11
    /// activation): the master gate for `crate::permissions` — when `false`
    /// (the default), `Agent::prepare_tool_call`'s tool-dispatch gate uses
    /// EXACTLY the pre-P5-1 [`Self::needs_approval`] path, byte-for-byte —
    /// no behavior change. `true` switches the gate to the richer
    /// canonicalized-command-aware [`crate::permissions::rules`] engine
    /// (deny→ask→allow first-match, C5), consulting
    /// [`Self::permissions_ask_patterns`] (together with the pre-existing
    /// [`Self::tool_deny_patterns`]/[`Self::tool_allow_patterns`] as the
    /// engine's deny/allow tiers) and [`Self::permissions_protected_paths`].
    pub permissions_enabled: bool,

    /// P5-1 (§3.1 `capabilities.permissions.rules.ask`, module 11): the
    /// engine's `ask` tier — the sibling of the pre-existing
    /// [`Self::tool_deny_patterns`]/[`Self::tool_allow_patterns`] (P4),
    /// which become the engine's `deny`/`allow` tiers respectively when
    /// [`Self::permissions_enabled`] is on (see
    /// `crate::permissions::rules::RuleSet`). Empty by default. Only
    /// consulted when [`Self::permissions_enabled`] is `true`.
    pub permissions_ask_patterns: Vec<String>,

    /// P5-1 (§3.1 `capabilities.permissions.protected_paths.paths`, module
    /// 13): glob patterns that are an unconditional DENY floor for both
    /// read and write access (cc§4 "never auto-approved… `.git/**`,
    /// `.env*`, …"), expanded via
    /// [`crate::permissions::rules::protected_path_deny_rules`] into the
    /// engine's `deny` tier. Empty by default. Only consulted when
    /// [`Self::permissions_enabled`] is `true`.
    ///
    /// **Honesty note on coverage (F4, Fable-5 adversarial review):** at
    /// the rule-engine layer this floor is enforced for (a) `read_file`/
    /// `write_file`/`edit_file`-shaped path calls, (b) a `bash`/`shell`
    /// command's direct output/input redirect targets (`>`, `>>`, `&>`,
    /// `>|`, `&>>`, `<`), (c) `apply_patch`'s target path(s), and (d) a
    /// best-effort set of known argv-writers (`tee`, `dd of=`, `cp`/`mv`/
    /// `install`, `sed -i`, `truncate`, `ln`) — see
    /// `crate::permissions::canon::known_writer_targets`'s doc comment for
    /// that heuristic's named gaps. A write this rule layer genuinely
    /// cannot statically resolve (an opaque wrapper — `eval`, `sh -c`, …
    /// — or a dynamic `$VAR`/`` `cmd` `` target) is forced to at least
    /// `Ask`, never silently `Allow`. What this layer does NOT provide is
    /// COMPLETE OS-level write confinement of arbitrary bash — that is
    /// `capabilities.permissions.sandbox`'s job (P5 module 10, a later
    /// unit), not this one's.
    pub permissions_protected_paths: Vec<String>,

    /// P5-1 (§3.1 `capabilities.permissions.sandbox.network.*`, module 12
    /// carry-forward): the domain allow/deny policy `crate::tools::WebFetchTool`/
    /// `WebSearchTool` enforce via `crate::tools::ToolContext::check_network`
    /// — the enforcement POINT already existed (P4c); this is its real
    /// config source (`crate::configfile::materialize_config`). `None` (the
    /// default) is byte-identical to today's behavior: no policy is
    /// enforced, exactly the honest gap `NetworkPolicy`'s own doc comment
    /// (`crate::tools`) already names.
    pub network_policy: Option<crate::tools::NetworkPolicy>,

    /// BP-10 (`capabilities.permissions.approvals.persist`, catalog row
    /// "Session approval caching"): whether an `AllowForSession` grant is
    /// remembered ACROSS processes, in a per-project store beside the
    /// session's other records (`crate::permissions::default_approval_store`).
    /// `false` (the default, and every config that never sets the key)
    /// keeps the pre-BP-10 in-memory cache: nothing is written, nothing is
    /// read, a new process re-asks.
    pub permissions_approvals_persist: bool,

    /// BP-10 (§2 module 14 `trust`, catalog row "Project/workspace trust
    /// gate"): the door the workspace-trust question is asked on — the
    /// SAME [`crate::permissions::PermissionsApprovalHandler`] every other
    /// `Ask` in this crate uses. `None` (the default) means no interactive
    /// trust door is attached, which `crate::trust::is_trusted` resolves
    /// per surface: config-declared CODE is refused, project instruction
    /// TEXT is loaded (see that module's doc comment).
    ///
    /// Lives on `Config` rather than on `Agent` because every surface trust
    /// gates is decided before or during `Agent` construction — a handler
    /// installed afterwards could never be asked.
    pub trust_handler: Option<std::sync::Arc<dyn crate::permissions::PermissionsApprovalHandler>>,

    /// BP-10 (embedder/test override): where this project's recorded trust
    /// decision lives. `None` (the default) uses
    /// `crate::trust::default_trust_store` — the same
    /// `$SUPERCODE_HOME`/project-tag layout the checkpoint store and the
    /// persisted approval cache use.
    pub trust_store: Option<PathBuf>,

    /// BP-10 (embedder/test override): where the persisted approval cache
    /// lives, when [`Self::permissions_approvals_persist`] is on. `None`
    /// (the default) uses `crate::permissions::default_approval_store` —
    /// the same `$SUPERCODE_HOME`-derived, per-project-tag layout
    /// [`Self::checkpoint_dir`] falls back to.
    pub permissions_approval_store: Option<PathBuf>,

    /// P5-10 (§3.1 `capabilities.permissions.sandbox.enabled`, module 12):
    /// whether the OS-level backstop (Landlock on Linux, seatbelt on
    /// macOS) is engaged for the `bash`/`shell` subprocess. `None` (the
    /// default — unset by the bare `sandbox = "<tier>"` shorthand, or a
    /// CLI `--sandbox` flag, neither of which touch this table key) keeps
    /// the PRE-P5-10 trigger byte-identical: `crate::sandbox::
    /// os_sandbox_active` falls back to "confine whenever the tier isn't
    /// `DangerFullAccess`", exactly what the macOS seatbelt path already
    /// did off `Self::sandbox` alone. `Some(false)` (the table form's
    /// explicit opt-out — `cc-parity`'s posture) turns the OS backstop off
    /// even for a confining tier; `Some(true)` forces it on.
    pub sandbox_os_enabled: Option<bool>,

    /// P5-10 (§3.1 `capabilities.permissions.sandbox.escalation`, module
    /// 12): what happens when a confining fs tier is requested but this
    /// platform/kernel can't enforce it — see
    /// [`crate::sandbox::SandboxEscalation`]. Defaults to `Deny`
    /// (fail-closed), matching `capabilities.permissions.sandbox`'s own
    /// `escalation = "deny"` config default.
    pub sandbox_escalation: crate::sandbox::SandboxEscalation,

    /// P5-10 (§3.1 `capabilities.permissions.sandbox.env_policy`, module
    /// 12): child-process environment sanitization for the spawned
    /// `bash`/`shell` subprocess — see
    /// [`crate::sandbox::SandboxEnvPolicy`]. Defaults to `Inherit`
    /// (byte-identical to pre-P5-10 behavior: the full environment passes
    /// through unchanged).
    pub sandbox_env_policy: crate::sandbox::SandboxEnvPolicy,

    /// P5-3 (§3.1 `capabilities.subagents.enabled`, module 9 activation):
    /// the master gate for the `spawn_subagent`/`subagent_status` agent
    /// the master gate for the `spawn_subagent`/`subagent_status` agent
    /// intrinsics — when `false` (the default), `Agent::tool_schemas` never
    /// advertises them and `Agent::run_tool`'s interception is a pure
    /// pass-through to the pre-P5-3 dispatch, byte-for-byte unchanged.
    pub subagents_enabled: bool,

    /// BP-7 (§2 module 7 `todos`, §3.1 `capabilities.todos.goals`, catalog
    /// §4a "Goals (persistent objective across turns)"): whether the
    /// session carries a standing objective — `/goal`, persisted as
    /// `<session>.goal.json`, restated at the tail of every request while
    /// it stands. Default `false`: an agent that never turns the knob on
    /// behaves exactly as before.
    pub goals_enabled: bool,
    /// P5-3 (§3.1 `capabilities.subagents.max_depth`, resource bound): the
    /// maximum spawn-tree depth — a depth-`max_depth` agent may not spawn
    /// (its child would land at `max_depth + 1`). Only consulted when
    /// [`Self::subagents_enabled`] is `true`.
    pub subagents_max_depth: usize,
    /// P5-3 (resource bound, NOT in the §3.1 illustrative schema snippet —
    /// added per the build brief's explicit "max concurrent subagents…
    /// cap, fail-closed... configurable"): the maximum number of subagents
    /// in flight anywhere in one spawn tree at once (root-to-leaf, shared
    /// via [`crate::agent::Agent`]'s concurrency gauge). Only consulted
    /// when [`Self::subagents_enabled`] is `true`.
    pub subagents_max_concurrent: usize,
    /// P5-3 (§3.1 `capabilities.subagents.background`): whether
    /// `spawn_subagent`'s `background: true` argument is honored at all —
    /// `false` (the default) refuses every background spawn regardless of
    /// [`Self::subagents_background_prompts`].
    pub subagents_background: bool,
    /// P5-3 (§2.2 C6, §3.1 `capabilities.subagents.background_prompts`):
    /// the auto-policy a background child's tool approvals route through.
    /// `None` (the default) means a background spawn is refused
    /// (`Error::SubagentBackgroundPolicyMissing`) — a detached child must
    /// never reach an interactive prompt it can't answer.
    pub subagents_background_prompts: Option<crate::subagents::BackgroundPromptsPolicy>,
    /// Claude Code emulation: advertise and accept its `Agent` tool name and
    /// argument vocabulary in addition to Supercode's native
    /// `spawn_subagent` intrinsic. Default `false`; enabled only for an
    /// explicitly imported Claude continuation.
    pub subagents_claude_agent_alias: bool,
    /// Claude Code resume compatibility for the scheduler-shaped
    /// `CronCreate`/`CronDelete`/`CronList`/`ScheduleWakeup` intrinsics.
    /// The imported manifest is always paused and these tools only mutate
    /// that inert state; no timer is started. Default `false` so ordinary
    /// agents do not gain a harness-specific tool surface.
    pub claude_runtime_tools_enabled: bool,
    /// P5-3 (§3.1 `capabilities.subagents.agents.<name>`, D3 "named-defs"):
    /// named subagent types, keyed by the name the model passes as
    /// `spawn_subagent`'s `agent_type` argument.
    pub subagents_definitions: HashMap<String, crate::subagents::NamedAgentDefinition>,
    /// P5-3 (runtime-only, NEVER set from a config file — only
    /// `Agent::run_spawn_subagent` sets it on a freshly-built CHILD
    /// `Config` before constructing that child): how deep in the spawn
    /// tree the agent built from this `Config` is. `0` is a top-level
    /// agent; a config file / [`ConfigBuilder`] caller that never spawns
    /// leaves this at its `0` default.
    pub subagent_depth: usize,

    /// P5-4 (§3.1 `capabilities.tui.enabled`, module 30 activation, §1.9
    /// recorded deviation): the master gate for the full-screen TUI —
    /// when `false` (the default), `crates/cli`'s `chat()` runs the
    /// pre-P5-4 rustyline REPL loop byte-for-byte, and every P5-4 seam
    /// below (`Agent::set_permissions_approval_handler`/
    /// `Agent::set_child_approval_handler_factory`/
    /// `crate::mcp::McpClient::set_elicitation_handler`) is simply never
    /// invoked with a TUI-backed implementation. `crates/cli`'s TUI runner
    /// additionally requires stdin/stdout/stderr all be a real tty before
    /// activating even when this is `true` — see that crate's
    /// `tui::should_activate` doc comment.
    pub tui_enabled: bool,
    /// P5-4 (§3.1 `capabilities.tui.theme`): `"dark"` | `"light"` — which
    /// built-in [`crate::tui::Theme`] the renderer starts with. Unknown or
    /// unset values fall back to `"dark"` (`crate::tui::Theme::default()`).
    pub tui_theme: String,
    /// P5-4 (§3.1 `capabilities.tui.vim_mode`, D8 "vim"): whether the
    /// input buffer starts in vim-style modal editing (normal/insert)
    /// rather than plain single-mode editing. See
    /// `crate::tui::InputMode`'s doc comment for the (deliberately
    /// basic — hjkl/i/a/o/dd/x) scope of what's implemented.
    pub tui_vim_mode: bool,
    /// P5-4 (§3.1 `capabilities.tui.keymap.<action> = "<key>"`,
    /// "configurable keybindings"): per-action key overrides layered on
    /// top of [`crate::tui::Keymap::default()`] — see that type's doc
    /// comment for the action names and key-spec syntax understood.
    pub tui_keymap: HashMap<String, String>,

    /// P5-5 (§3.1 `capabilities.session_tree.enabled`, design §2 module 21
    /// activation): the master gate for the native in-place session tree
    /// (`supercode_interchange::session_tree`) — a pure "does the harness advertise/prefer
    /// tree-mode session semantics" signal for a caller (CLI/TUI) to consult.
    /// `false` (the default, matching every `HarnessConfig` that never sets
    /// this table) changes nothing about [`supercode_interchange::session_tree::SessionTree`]
    /// itself, which has no runtime dependency on this flag (a caller can
    /// always construct/use one directly, exactly like
    /// [`crate::store::SessionStore::fork`] isn't gated on any capability
    /// either) — this field exists purely so a future integration point has
    /// a resolved config signal to read, matching every other P5 module's
    /// "carried on `Config`, pure config → set" convention.
    pub session_tree_enabled: bool,
    /// P5-5 (§3.1 `capabilities.session_tree.branch_summaries`, module 21
    /// "branch summaries"): whether a caller wiring
    /// [`supercode_interchange::session_tree::SessionTree::splice_for_linear_export`] into a
    /// C7 linear-export path should generate/attach summaries for off-path
    /// branches at all, vs. leaving them unsummarized (still fully present
    /// in the sidecar either way — this only controls the human-readable
    /// digest, never the underlying lossless data). Defaults `true` (the
    /// §3.1 schema's own default) when [`Self::session_tree_enabled`] is
    /// `true` and this key is unset.
    pub session_tree_branch_summaries: bool,
    /// P5-5 (§3.1 `capabilities.session_tree.labels`, module 21 "entry
    /// labels"): whether a caller's UI/CLI surface should expose
    /// [`supercode_interchange::session_tree::SessionTree::label`]/`clear_label` at all.
    /// Defaults `true` (the §3.1 schema's own default) when
    /// [`Self::session_tree_enabled`] is `true` and this key is unset. Like
    /// [`Self::session_tree_branch_summaries`], this is advisory — the
    /// underlying `SessionTree` API always supports labeling regardless.
    pub session_tree_labels: bool,
    /// P5-6 (§3.1 `capabilities.tools_background.enabled`, module 4
    /// activation): the master gate for the `background_exec`/
    /// `background_status`/`background_list`/`background_kill` agent
    /// intrinsics — when `false` (the default), `Agent::tool_schemas`
    /// never advertises them and `Agent::prepare_tool_call`'s interception
    /// is a pure pass-through to the pre-P5-6 dispatch, byte-for-byte
    /// unchanged (a hallucinated call falls through to the ordinary
    /// unknown-tool error, exactly like `spawn_subagent`'s own disabled
    /// posture).
    pub tools_background_enabled: bool,
    /// P5-6 (resource bound, NOT in the §3.1 illustrative schema snippet —
    /// added per the build brief's explicit "max-concurrent cap,
    /// fail-closed", mirroring [`Self::subagents_max_concurrent`]'s own
    /// precedent): the maximum number of background jobs this agent may
    /// have running at once. Only consulted when
    /// [`Self::tools_background_enabled`] is `true`.
    pub tools_background_max_concurrent: usize,
    /// P5-6 (resource bound, "must not OOM" — mirrors
    /// `crate::mcp::MCP_MAX_RESPONSE_BYTES`'s hardening-cap precedent): the
    /// maximum number of bytes of combined stdout/stderr retained per
    /// background job — output beyond this is truncated-with-marker, never
    /// buffered further (`supercode_runtime::background::CapturedOutput::append`).
    /// Only consulted when [`Self::tools_background_enabled`] is `true`.
    pub tools_background_max_output_bytes: usize,
    /// P5-9 (§3.1 `capabilities.checkpoint.enabled`, module 20 activation):
    /// the master gate for file checkpointing — when `false` (the
    /// default), `crate::agent::build_tool_context` never touches disk for
    /// this at all: no `crate::checkpoint::CheckpointStore` is opened, no
    /// shadow directory is created, `ToolContext::write_observer` stays
    /// `None`, and every write-tool call site's observer branch is a
    /// pure no-op — byte-identical to before this module existed. See
    /// `crate::checkpoint`'s module doc comment for the full design.
    pub checkpoint_enabled: bool,
    /// P5-9 (bounded-disk requirement, NOT in the §3.1 illustrative schema
    /// snippet — added per the build brief's explicit "bounded... no
    /// unbounded disk growth", mirroring [`Self::tools_background_max_concurrent`]'s
    /// own precedent): the maximum number of checkpoints retained per
    /// project before the oldest are pruned. Only consulted when
    /// [`Self::checkpoint_enabled`] is `true`.
    pub checkpoint_retain: usize,
    /// P5-9 (embedder/test override, NOT a `[capabilities.checkpoint]`
    /// schema key — this is a Rust-only knob, the same class as
    /// [`Self::pre_tool_hook`]/[`Self::post_tool_hook`]): where the shadow
    /// store lives. `None` (the default) means
    /// `crate::checkpoint::observer_for_config` derives the location from
    /// `crate::agent::global_instructions_dir()` + a hash of [`Self::cwd`]
    /// (mirroring the CLI's own `cwd_tag` precedent) — set this to make the
    /// location hermetic/deterministic (tests; embedders that want a
    /// specific on-disk layout) without touching process-global env vars.
    pub checkpoint_dir: Option<PathBuf>,

    /// BP-7 (§3.1 `capabilities.checkpoint.restore`, catalog §4a "Turn diff
    /// tracking"): whether this harness may RESTORE from a checkpoint, as
    /// opposed to only tracking each turn's diff. `true` (the default, and
    /// cc-parity's posture) is CC's `/rewind`. `false` is Codex's shape: a
    /// real `turn_diff_tracker` with no code restore behind it.
    pub checkpoint_restore: bool,
    /// P5-11 (§3.1 `capabilities.lsp.enabled`, module 28 activation): the
    /// master gate for LSP server lifecycle + edit-path diagnostics (D1).
    /// `false` (the default) means `crate::agent::build_tool_context` never
    /// touches `crate::lsp::manager_for_config` at all — no child process
    /// is ever spawned, `ToolContext::write_observer`'s chain never gains
    /// an LSP entry — byte-identical to before this module existed. See
    /// `crate::lsp`'s module doc comment for the accepted gaps (no
    /// auto-provisioned server fleet, no symbol-indexing query tool).
    pub lsp_enabled: bool,
    /// P5-11 (`capabilities.lsp.servers.<name>`): the configured language
    /// servers, in alphabetical order by server name (a TOML table has no
    /// inherent ordering — `configfile::materialize_config` sorts
    /// explicitly for reproducibility) — first extension match wins. Only
    /// consulted when [`Self::lsp_enabled`] is `true`. An empty `Vec` with
    /// `lsp_enabled = true` is legal but warns once
    /// (`crate::lsp::manager_for_config`) — very likely a config mistake.
    pub lsp_servers: Vec<(String, crate::lsp::LspServerSpec)>,
    /// P5-11 (bounded-context requirement, NOT in the §3.1 illustrative
    /// schema snippet — added per the build brief's explicit "a flood
    /// mustn't blow context", mirroring [`Self::tools_background_max_output_bytes`]'s
    /// own precedent): the maximum number of diagnostics rendered into a
    /// single tool result. Only consulted when [`Self::lsp_enabled`] is
    /// `true`.
    pub lsp_max_diagnostics: usize,
    /// P5-11 (bounded-latency requirement): how long to wait for a
    /// configured server to publish diagnostics after a
    /// `didOpen`/`didChange` before giving up gracefully. Only consulted
    /// when [`Self::lsp_enabled`] is `true`.
    pub lsp_timeout_secs: u64,
    /// P5-11 (§3.1 `capabilities.formatters.enabled`, module 29
    /// activation): the master gate for format-on-write. `false` (the
    /// default) means the shared D-5 write-observer chain never gains a
    /// `crate::formatters::FormatObserver` entry — byte-identical to
    /// before this module existed.
    pub formatters_enabled: bool,
    /// P5-11 (`capabilities.formatters.<name>`): the configured formatter
    /// commands, in alphabetical order by formatter name (same "TOML has
    /// no inherent ordering" rationale as [`Self::lsp_servers`]) — first
    /// extension match wins. Only consulted when
    /// [`Self::formatters_enabled`] is `true`.
    pub formatters: Vec<(String, crate::formatters::FormatterSpec)>,
    /// P5-11 (§3.1 `capabilities.formatters.diff_back`, C10): whether a
    /// formatter's rewrite is diffed back into the calling tool's result
    /// so the model's file-memory stays truthful (design line 534, "must
    /// diff-back into the result"). `true` is the C10-SAFE default; `false`
    /// still runs the formatter but withholds the annotation — legal, but
    /// the model then has a stale belief about the file's exact bytes
    /// until it re-reads it.
    pub formatters_diff_back: bool,
    /// P5-11 (bounded-latency requirement, "a hanging formatter can't hang
    /// the loop — timeout + kill like hooks"): how long a single formatter
    /// invocation may run before it's treated as failed (the file is left
    /// untouched). Only consulted when [`Self::formatters_enabled`] is
    /// `true`.
    pub formatters_timeout_secs: u64,
    /// P5-12 (§2 module 14 `trust`, D-10): the master gate for the
    /// project/workspace trust concept — `false` (the default) means
    /// [`Self::trust_default`] is never consulted and [`crate::plugins`]
    /// treats every plugin as untrusted (see
    /// [`crate::plugins::is_trusted`]'s doc comment). `[capabilities.trust]`
    /// is project-forbidden (`configfile::PROJECT_FORBIDDEN_CAPABILITY_TABLES`
    /// / `userconfig`'s own copy): only the user/global layer — or a
    /// preset extended from it — may ever set this, exactly like
    /// `hooks`/`plugins`/`server` (a project asserting its OWN trust would
    /// defeat the entire point of the gate).
    pub trust_enabled: bool,
    /// P5-12 (`capabilities.trust.default`): the workspace-trust decision —
    /// see [`crate::plugins::TrustDecision`]'s doc comment for why, absent a
    /// wired interactive upgrade flow, only [`crate::plugins::TrustDecision::Always`]
    /// actually unlocks plugin loading in this build (an honest,
    /// documented gap — not a silent no-op: `ask`/`never` both cleanly
    /// refuse, they don't pretend to prompt). Only consulted when
    /// [`Self::trust_enabled`] is `true`.
    pub trust_default: crate::plugins::TrustDecision,
    /// P5-12 (§2 module 18 `plugins`, §3.1 `capabilities.plugins.enabled`):
    /// the master gate for out-of-process, manifest-declared plugins (see
    /// [`crate::plugins`]'s module doc comment for the ABI). `false` (the
    /// default) means `crate::agent`'s tool-registration path never touches
    /// [`crate::plugins::discover_and_load`] at all — no directory read, no
    /// manifest parse, no subprocess — byte-identical to before this module
    /// existed.
    pub plugins_enabled: bool,
    /// P5-12 (`capabilities.plugins.dirs`): EXTRA directories to scan for
    /// `<plugin-name>/plugin.toml` manifests, on top of the always-scanned
    /// `$SUPERCODE_HOME/plugins` (see [`crate::plugins::discover_manifests`]).
    /// `[capabilities.plugins]` (this field included) is project-forbidden,
    /// so this can only ever come from the trusted user/global layer or a
    /// preset. Only consulted when [`Self::plugins_enabled`] is `true` AND
    /// the workspace is trusted (see [`crate::plugins::is_trusted`]).
    pub plugins_dirs: Vec<PathBuf>,
}

/// P4e (§1.4/§3.1 `core.context_injections`): one named ambient context
/// block -- see [`Config::context_injection_blocks`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ContextInjectionBlock {
    /// The block's heading, rendered as `# {name}`.
    pub name: String,
    /// The block's body text, appended verbatim under the heading.
    pub content: String,
}

impl ContextInjectionBlock {
    /// Build a named block.
    pub fn new(name: impl Into<String>, content: impl Into<String>) -> Self {
        ContextInjectionBlock {
            name: name.into(),
            content: content.into(),
        }
    }
}

/// How queued steering/follow-up messages are drained (S1.7, pi3
/// `steeringMode`/`followUpMode`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SteeringMode {
    /// Deliver every queued message at once.
    All,
    /// Deliver exactly one queued message per drain point (the default).
    #[default]
    OneAtATime,
}

impl SteeringMode {
    /// Parse the `"all"` / `"one-at-a-time"` config strings (S3.1).
    pub fn parse(s: &str) -> Option<SteeringMode> {
        match s {
            "all" => Some(SteeringMode::All),
            "one-at-a-time" | "one_at_a_time" => Some(SteeringMode::OneAtATime),
            _ => None,
        }
    }
}

/// A stop-gate hook: receives the would-be-final assistant message; returns
/// `Some(reason)` to veto termination and continue the loop (the reason is
/// injected as a new user message), or `None` to allow the stop. See
/// `Config::stop_gate`.
pub type StopGateHook = Box<dyn Fn(&str) -> Option<String> + Send + Sync>;

impl Default for Config {
    fn default() -> Self {
        Config {
            model: "anthropic/claude-opus-4-8".to_string(),
            base_url: OPENROUTER_BASE_URL.to_string(),
            api_key: None,
            api_key_env: DEFAULT_API_KEY_ENV.to_string(),
            api_key_cmd: None,
            api_key_command: None,
            update_check: false,
            system_prompt: DEFAULT_SYSTEM_PROMPT.to_string(),
            temperature: None,
            max_tokens: None,
            max_iterations: 25,
            effort: None,
            response_format: None,
            extra_body: serde_json::Map::new(),
            max_total_output_tokens: None,
            max_budget_usd: None,
            max_steps: None,
            price_input_per_mtok: None,
            price_output_per_mtok: None,
            max_tool_output_bytes: Some(100_000),
            tool_output_spill: false,
            cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
            additional_dirs: Vec::new(),
            load_project_context: false,
            sandbox: crate::tools::SandboxPolicy::default(),
            approval: ApprovalPolicy::default(),
            auto_approved_tools: std::collections::HashSet::new(),
            tool_deny_patterns: Vec::new(),
            tool_allow_patterns: Vec::new(),
            approval_handler: None,
            pre_tool_hook: None,
            post_tool_hook: None,
            lifecycle_hook: None,
            prompts: default_prompts(),
            compact_after_messages: None,
            tool_overrides: HashMap::new(),
            tool_advertising: ToolAdvertising::default(),
            extra_headers: HashMap::new(),
            event_sink: None,
            cache_plan: CachePlan::default(),
            reduction_policy: ReductionPolicySettings::default(),
            handoff_enabled: true,
            tool_schema_tier: crate::tools::SchemaTier::default(),
            cache_warnings: true,
            module_registry: false,
            module_activation: crate::modules::ModuleActivation::default(),
            core_tools_enabled: ["read_file", "bash", "edit_file", "write_file"]
                .iter()
                .map(|s| s.to_string())
                .collect(),
            skills_enabled: false,
            skills_harness: None,
            skills_dirs: Vec::new(),
            skills_implicit_match: false,
            skills_shell_injection: false,
            file_mentions: false,
            output_style: String::new(),
            path_rules: false,
            model_family_prompts: std::collections::BTreeMap::new(),
            small_model: None,
            model_fallback: Vec::new(),
            model_routing: crate::model_catalog::Routing::default(),
            service_tier: None,
            env_context: false,
            project_root_markers: vec![".git".to_string()],
            project_doc_max_bytes: None,
            project_doc_excludes: Vec::new(),
            project_doc_strip_comments: false,
            instruction_imports: false,
            retry_enabled: true,
            retry_max_retries: None,
            retry_base_delay_ms: None,
            compaction_reserve_tokens: None,
            compaction_keep_recent_tokens: None,
            compaction_focus_instructions: None,
            auto_title: false,
            steering_mode: SteeringMode::default(),
            follow_up_mode: SteeringMode::default(),
            stop_gate: None,
            read_file_multimodal: false,
            read_file_line_numbers: false,
            edit_file_require_read_before_edit: false,
            edit_file_notebook_aware: false,
            shell_env_snapshot: false,
            doom_loop_threshold: None,
            nested_instructions: false,
            model_switch_allow_switch: false,
            model_switch_notice: false,
            plan_mode_effort: None,
            context_injections: false,
            context_injection_blocks: Vec::new(),
            // P4e: `true` because today's behavior (before this master gate
            // existed) is "compaction fires whenever a trigger is
            // configured" -- a default of `true` preserves that exactly;
            // only an explicit `false` newly suppresses it.
            compaction_enabled: true,
            // BP-1: `true` because today's compaction marker has always
            // said "summarized"; only an explicit `summarize = false`
            // changes the text.
            compaction_summarize: true,
            parallel_tool_calls: false,
            session_git_metadata: false,
            session_dir: None,
            session_persist: true,
            session_name: None,
            session_retention_days: None,
            session_append_only: false,
            session_queue_persist: false,
            todos_persist: false,
            session_export_format: crate::human_export::HumanExportFormat::default(),
            permissions_enabled: false,
            permissions_ask_patterns: Vec::new(),
            permissions_protected_paths: Vec::new(),
            network_policy: None,
            trust_handler: None,
            trust_store: None,
            permissions_approvals_persist: false,
            permissions_approval_store: None,
            sandbox_os_enabled: None,
            sandbox_escalation: crate::sandbox::SandboxEscalation::default(),
            sandbox_env_policy: crate::sandbox::SandboxEnvPolicy::default(),
            subagents_enabled: false,
            goals_enabled: false,
            subagents_max_depth: 2,
            subagents_max_concurrent: 4,
            subagents_background: false,
            subagents_background_prompts: None,
            subagents_claude_agent_alias: false,
            claude_runtime_tools_enabled: false,
            subagents_definitions: HashMap::new(),
            subagent_depth: 0,
            tui_enabled: false,
            tui_theme: "dark".to_string(),
            tui_vim_mode: false,
            tui_keymap: HashMap::new(),
            session_tree_enabled: false,
            session_tree_branch_summaries: false,
            session_tree_labels: false,
            tools_background_enabled: false,
            tools_background_max_concurrent: supercode_runtime::background::DEFAULT_MAX_CONCURRENT,
            tools_background_max_output_bytes:
                supercode_runtime::background::DEFAULT_MAX_OUTPUT_BYTES,
            checkpoint_enabled: false,
            checkpoint_retain: crate::checkpoint::DEFAULT_RETAIN,
            checkpoint_dir: None,
            checkpoint_restore: true,
            lsp_enabled: false,
            lsp_servers: Vec::new(),
            lsp_max_diagnostics: crate::lsp::DEFAULT_LSP_MAX_DIAGNOSTICS,
            lsp_timeout_secs: crate::lsp::DEFAULT_LSP_TIMEOUT_SECS,
            formatters_enabled: false,
            formatters: Vec::new(),
            formatters_diff_back: true,
            formatters_timeout_secs: crate::formatters::DEFAULT_FORMATTER_TIMEOUT_SECS,
            trust_enabled: false,
            trust_default: crate::plugins::TrustDecision::Ask,
            plugins_enabled: false,
            plugins_dirs: Vec::new(),
        }
    }
}

impl Config {
    /// Start building a [`Config`] from defaults.
    pub fn builder() -> ConfigBuilder {
        ConfigBuilder {
            config: Config::default(),
        }
    }

    /// Whether a tool is enabled given the overrides (defaults to enabled).
    pub fn tool_enabled(&self, name: &str) -> bool {
        self.tool_overrides
            .get(name)
            .and_then(|o| o.enabled)
            .unwrap_or(true)
    }

    /// Whether a tool call requires approval before it runs, given the
    /// policy, the auto-approve allowlist, and (P4) the deny/allow glob
    /// PATTERN lists — see [`Self::tool_deny_patterns`]/
    /// [`Self::tool_allow_patterns`]'s doc comments for the exact
    /// semantics. Both are empty by default, so this is byte-identical to
    /// pre-P4 behavior for any `Config` that doesn't set them.
    pub fn needs_approval(&self, tool: &str) -> bool {
        // Deny wins unconditionally, even under `Never` — a deny pattern is
        // a hard floor, not just another allowlist entry.
        if self.tool_deny_patterns.iter().any(|p| glob_match(p, tool)) {
            return true;
        }
        match self.approval {
            ApprovalPolicy::Never => false,
            // P5-1: this coarse, tool-name-only gate has no model-escalation
            // signal to consult (that requires the canonicalized-command
            // context only `crate::permissions`'s richer gate has), so
            // `ModelRequested` is treated the same, conservative way
            // `OnRequest` is here — the safe simplification documented on
            // `ApprovalPolicy::ModelRequested` itself. The P5-1 engine
            // (active when `Self::permissions_enabled` is `true`) is where
            // Codex's real "mostly silent, escalation asks" posture is
            // approximated instead.
            ApprovalPolicy::OnRequest | ApprovalPolicy::ModelRequested => {
                !self.auto_approved_tools.contains(tool)
                    && !self.tool_allow_patterns.iter().any(|p| glob_match(p, tool))
            }
            // BP-8 DEFECT-FIX (see the same change in the P5-1 engine's own
            // default, `Agent::tool_decision`): an EXPLICIT
            // `auto_approved_tools` entry is CC's read-only tier, which
            // never prompts (cc§4 "Tiered defaults"). A glob ALLOW pattern
            // still exempts nothing here — that stays `OnRequest`-only, so
            // `*` cannot quietly turn `untrusted` into `never`.
            ApprovalPolicy::Untrusted => !self.auto_approved_tools.contains(tool),
        }
    }

    /// The effective description for a tool, applying any override.
    pub fn tool_description<'a>(&'a self, name: &str, builtin: &'a str) -> &'a str {
        self.tool_overrides
            .get(name)
            .and_then(|o| o.description.as_deref())
            .unwrap_or(builtin)
    }

    /// The effective schema tier for a tool (TR-8/T5): a per-tool override if
    /// set, else the global [`Self::tool_schema_tier`].
    pub fn schema_tier_for(&self, name: &str) -> crate::tools::SchemaTier {
        self.tool_overrides
            .get(name)
            .and_then(|o| o.schema_tier)
            .unwrap_or(self.tool_schema_tier)
    }
}

/// A single tool's file-settable overrides — the `ConfigProfile` mirror of
/// [`ToolOverride`] (COMPOSABLE-HARNESS-DESIGN.md §3.1 `[core.tools.<name>]`,
/// §3.2 mapping row `core.tools.enabled` + `[core.tools.<n>].*`).
#[derive(Debug, Clone, Default, serde::Deserialize)]
pub struct ToolOverrideProfile {
    /// `Some(false)` hides the tool from the model entirely.
    pub enabled: Option<bool>,
    /// Replaces the tool's built-in description.
    pub description: Option<String>,
    /// Per-tool schema tier: `full` | `medium` | `minimal`.
    pub schema_tier: Option<String>,
    /// P4e (§3.1 `core.tools.bash.timeout_secs`, S14) -- see
    /// `ToolOverride::timeout_secs`. Only meaningful on the `bash` entry.
    pub timeout_secs: Option<u64>,
}

/// The serializable subset of a [`Config`] that can live in a config file.
/// (Callbacks/handlers are code-only and are not represented here.)
///
/// Grown from its original 9 fields to the P1 §3.2 surface
/// (COMPOSABLE-HARNESS-DESIGN.md §5.2 "P1" migration step): every `[core]`
/// scalar/table/array `Config` maps to lives here so it becomes file-settable
/// for the first time, per the design's stated framing gap (§3.0).
#[derive(Debug, Clone, Default, serde::Deserialize)]
pub struct ConfigProfile {
    /// Model id.
    pub model: Option<String>,
    /// Endpoint base URL.
    pub base_url: Option<String>,
    /// Environment variable to read the API key from (§3.1 `core.api_key_env`;
    /// §3.2: "today absent from BOTH files").
    pub api_key_env: Option<String>,
    /// Credential-helper command (§3.1 `core.api_key_cmd`, D6 row) — see
    /// [`Config::api_key_cmd`].
    pub api_key_cmd: Option<String>,
    /// Argv credential helper (§3.1 `core.api_key_command`, D6 row) — see
    /// [`Config::api_key_command`]; arrays replace.
    pub api_key_command: Option<Vec<String>>,
    /// Startup release check (§3.1 `core.update_check`, D6 row) — see
    /// [`Config::update_check`].
    pub update_check: Option<bool>,
    /// System prompt.
    pub system_prompt: Option<String>,
    /// P4 (§3.1 `core.append_system_prompt`, D2 row 1): an additive suffix
    /// composed onto whatever [`Self::system_prompt`] resolves to (the
    /// profile's own value if set, else whatever the builder already had —
    /// see [`ConfigBuilder::apply_profile`]'s composition order), distinct
    /// from REPLACING it. `[project-forbidden]`, same trust boundary as
    /// `system_prompt` (§3.3: prompt injection).
    pub append_system_prompt: Option<String>,
    /// Sampling temperature.
    pub temperature: Option<f32>,
    /// Output token cap per request.
    pub max_tokens: Option<u32>,
    /// Reasoning/effort level.
    pub effort: Option<String>,
    /// Sandbox policy: `read_only` | `workspace_write` | `danger_full_access`.
    pub sandbox: Option<String>,
    /// Approval policy: `never` | `on_request` | `untrusted`.
    pub approval: Option<String>,
    /// Auto-load CLAUDE.md / AGENTS.md.
    pub project_context: Option<bool>,
    /// Per-`send` iteration budget (§3.1 `core.max_iterations`).
    pub max_iterations: Option<usize>,
    /// Extra roots beyond `cwd` (§3.1 `core.additional_dirs`); arrays
    /// replace wholesale on overlay (§3.3).
    pub additional_dirs: Option<Vec<String>>,
    /// Compact once the conversation exceeds this many messages (§3.1
    /// `core.compaction.after_messages`; `0` = trigger off).
    pub compact_after_messages: Option<usize>,
    /// Prompt-caching plan: `off` | `imported_prefix` (§3.1
    /// `capabilities.cache.plan`).
    pub cache_plan: Option<String>,
    /// BP-4 (§3.1 `capabilities.cache.warnings`): whether cache-churn
    /// warnings are surfaced in-session -- see `Config::cache_warnings`.
    /// `None` leaves the default (on) in place.
    pub cache_warnings: Option<bool>,
    /// How tools are advertised: `full` | `deferred` (§3.1
    /// `capabilities.deferred_tools`).
    pub tool_advertising: Option<String>,
    /// The eagerly-advertised core allowlist when `tool_advertising =
    /// "deferred"` (§3.1 `capabilities.deferred_tools.core`); arrays replace.
    pub tool_advertising_core: Option<Vec<String>>,
    /// Global tool-schema tier: `full` | `medium` | `minimal` (§3.1
    /// `core.tools.schema_tier`).
    pub schema_tier: Option<String>,
    /// Tools that never require approval under `ApprovalPolicy::OnRequest`
    /// (§3.1 `capabilities.permissions.auto_approved_tools`); arrays replace.
    pub auto_approved_tools: Option<Vec<String>>,
    /// P4: deny-pattern generalization of `auto_approved_tools` (§3.1
    /// `capabilities.permissions.rules.deny`) — see
    /// [`Config::tool_deny_patterns`]. Arrays replace.
    pub tool_deny_patterns: Option<Vec<String>>,
    /// P4: allow-pattern generalization of `auto_approved_tools` (§3.1
    /// `capabilities.permissions.rules.allow`) — see
    /// [`Config::tool_allow_patterns`]. Arrays replace.
    pub tool_allow_patterns: Option<Vec<String>>,
    /// Extra HTTP headers merged in (§3.1 `core.extra_headers`); a table,
    /// merged key-wise on overlay (§3.3).
    pub extra_headers: Option<HashMap<String, String>>,
    /// Extra request-body fields merged in (§3.1 `core.extra_body`); a
    /// table, merged key-wise on overlay (§3.3).
    pub extra_body: Option<serde_json::Map<String, serde_json::Value>>,
    /// Max bytes of a single tool result (§3.1 `core.max_tool_output_bytes`).
    pub max_tool_output_bytes: Option<usize>,
    /// Cap on cumulative output tokens per `send` loop (§3.1
    /// `core.max_total_output_tokens`).
    pub max_total_output_tokens: Option<u64>,
    /// BP-7 (`core.max_budget_usd`) — see [`Config::max_budget_usd`].
    pub max_budget_usd: Option<f64>,
    /// BP-7 (`core.max_steps`) — see [`Config::max_steps`].
    pub max_steps: Option<usize>,
    /// BP-7 (`core.price_input_per_mtok`) — see
    /// [`Config::price_input_per_mtok`].
    pub price_input_per_mtok: Option<f64>,
    /// BP-7 (`core.price_output_per_mtok`) — see
    /// [`Config::price_output_per_mtok`].
    pub price_output_per_mtok: Option<f64>,
    /// Named prompt templates (§3.1 `[core.prompts]`); a table, merged
    /// key-wise (new/overridden names layer onto the built-ins, they don't
    /// wholesale-replace them).
    pub prompts: Option<HashMap<String, String>>,
    /// Per-tool enable/disable + description/schema-tier overrides, keyed
    /// by tool name (§3.1 `[core.tools.<name>]`, §3.2 "today in no file");
    /// a table, merged key-wise per tool.
    pub tool_overrides: Option<HashMap<String, ToolOverrideProfile>>,

    /// P4b (S3.1 `core.env_context`) -- see `Config::env_context`.
    pub env_context: Option<bool>,
    /// P4b (S3.1 `core.project_root_markers`) -- see
    /// `Config::project_root_markers`; arrays replace.
    pub project_root_markers: Option<Vec<String>>,
    /// P4b (S3.1 `core.project_doc_max_bytes`) -- see
    /// `Config::project_doc_max_bytes`.
    pub project_doc_max_bytes: Option<usize>,
    /// BP-4 (`core.project_doc_excludes`) -- see
    /// `Config::project_doc_excludes`; arrays replace.
    pub project_doc_excludes: Option<Vec<String>>,
    /// BP-4 (`core.project_doc_strip_comments`) -- see
    /// `Config::project_doc_strip_comments`.
    pub project_doc_strip_comments: Option<bool>,
    /// P4b (S3.1 `core.instruction_imports`) -- see
    /// `Config::instruction_imports`.
    pub instruction_imports: Option<bool>,
    /// P4b (S3.1 `core.retry.enabled`) -- see `Config::retry_enabled`.
    pub retry_enabled: Option<bool>,
    /// P4b (S3.1 `core.retry.max_retries`) -- see `Config::retry_max_retries`.
    pub retry_max_retries: Option<u32>,
    /// P4b (S3.1 `core.retry.base_delay_ms`) -- see
    /// `Config::retry_base_delay_ms`.
    pub retry_base_delay_ms: Option<u64>,
    /// P4b (S3.1 `core.compaction.reserve_tokens`) -- see
    /// `Config::compaction_reserve_tokens`.
    pub compaction_reserve_tokens: Option<u64>,
    /// P4b (S3.1 `core.compaction.keep_recent_tokens`) -- see
    /// `Config::compaction_keep_recent_tokens`.
    pub compaction_keep_recent_tokens: Option<u64>,
    /// P4b (S3.1 `core.compaction.focus_instructions`) -- see
    /// `Config::compaction_focus_instructions`.
    pub compaction_focus_instructions: Option<String>,
    /// P4b (S3.1 `core.session.auto_title`) -- see `Config::auto_title`.
    pub auto_title: Option<bool>,
    /// P4b (S3.1 `core.steering.steering_mode`) -- see
    /// `Config::steering_mode`.
    pub steering_mode: Option<String>,
    /// P4b (S3.1 `core.steering.follow_up_mode`) -- see
    /// `Config::follow_up_mode`.
    pub follow_up_mode: Option<String>,

    /// P4c (S3.1 `core.tools.read_file.multimodal`) -- see
    /// `Config::read_file_multimodal`.
    pub read_file_multimodal: Option<bool>,
    /// BP-2 (S3.1 `core.tools.read_file.line_numbers`) -- see
    /// `Config::read_file_line_numbers`.
    pub read_file_line_numbers: Option<bool>,
    /// BP-2 (S3.1 `core.tool_output_spill`) -- see
    /// `Config::tool_output_spill`.
    pub tool_output_spill: Option<bool>,
    /// P4c (S3.1 `core.tools.edit_file.require_read_before_edit`) -- see
    /// `Config::edit_file_require_read_before_edit`.
    pub edit_file_require_read_before_edit: Option<bool>,
    /// P4c (S3.1 `core.tools.edit_file.notebook_aware`) -- see
    /// `Config::edit_file_notebook_aware`.
    pub edit_file_notebook_aware: Option<bool>,
    /// P4c (S3.1 `core.shell_env_snapshot`) -- see
    /// `Config::shell_env_snapshot`.
    pub shell_env_snapshot: Option<bool>,
    /// P4c (S3.1 `core.doom_loop_threshold`) -- see
    /// `Config::doom_loop_threshold`.
    pub doom_loop_threshold: Option<u32>,
    /// P4c (S3.1 `core.nested_instructions`) -- see
    /// `Config::nested_instructions`.
    pub nested_instructions: Option<bool>,
    /// P4c (S3.1 `core.model_switch.allow_switch`) -- see
    /// `Config::model_switch_allow_switch`.
    pub model_switch_allow_switch: Option<bool>,
    /// BP-13 (S3.1 `core.model_switch.notice`) -- see
    /// `Config::model_switch_notice`.
    pub model_switch_notice: Option<bool>,

    /// P4e (S3.1 `core.context_injections`) -- see
    /// `Config::context_injections`. Only the boolean gate is
    /// file/profile-settable; `Config::context_injection_blocks`' actual
    /// content is code-only (see its doc comment).
    pub context_injections: Option<bool>,
    /// P4e (S3.1 `core.compaction.enabled`) -- see
    /// `Config::compaction_enabled`.
    pub compaction_enabled: Option<bool>,
    /// BP-1 (S3.1 `core.compaction.summarize`) -- see
    /// `Config::compaction_summarize`.
    pub compaction_summarize: Option<bool>,
    /// P4e (S3.1 `core.parallel_tool_calls`) -- see
    /// `Config::parallel_tool_calls`.
    pub parallel_tool_calls: Option<bool>,
    /// P4e (S3.1 `core.session.git_metadata`) -- see
    /// `Config::session_git_metadata`.
    pub session_git_metadata: Option<bool>,
    /// P4e (S3.1 `core.session.dir`) -- see `Config::session_dir`.
    pub session_dir: Option<String>,
    /// P4e (S3.1 `core.session.persist`) -- see `Config::session_persist`.
    pub session_persist: Option<bool>,
    /// P4e (S3.1 `core.session.name`) -- see `Config::session_name`.
    pub session_name: Option<String>,
    /// P4e (S3.1 `core.session.retention_days`) -- see
    /// `Config::session_retention_days`.
    pub session_retention_days: Option<u32>,
    /// P4e (S3.1 `core.session.export_format`) -- see
    /// `Config::session_export_format`. `"text"` | `"html"`; an
    /// unrecognized string is a no-op warning, like `steering_mode`.
    pub session_export_format: Option<String>,
    /// BP-8 (S3.1 `core.session.append_only`) -- see
    /// `Config::session_append_only`.
    pub session_append_only: Option<bool>,
    /// BP-8 (S3.1 `core.session.queue_persist`) -- see
    /// `Config::session_queue_persist`.
    pub session_queue_persist: Option<bool>,
}

/// BP-9 (§3.1 `core.project_root_markers`, catalog:232 "Project-root
/// detection markers", cx§6, oc§6): the project root for `cwd` — the
/// NEAREST ancestor (starting at `cwd` itself) that directly contains any
/// entry named by `markers`. `None` when no ancestor carries a marker, or
/// when `markers` is empty (an empty marker list is an explicit "don't do
/// root detection", not an invitation to walk to `/`).
///
/// This is the ONE walk every marker consumer shares — the git-status probe
/// in `env_context`, the CLI's `.supercode.toml` discovery, and prompt
/// assembly's instruction walk. Sharing it is the point: "where does the
/// project stop?" must have exactly one answer per config, or the same
/// `project_root_markers` value would mean three different things.
///
/// A marker matches whether it is a file or a directory (`.git` is a
/// directory in a normal checkout and a FILE in a worktree/submodule —
/// both are the root). Symlinks are followed by `exists()`, and the walk is
/// purely lexical on `cwd` as given: no canonicalization, so a caller that
/// wants symlink-resolved semantics canonicalizes before calling.
pub fn project_root_for(cwd: &std::path::Path, markers: &[String]) -> Option<std::path::PathBuf> {
    if markers.is_empty() {
        return None;
    }
    let mut dir = Some(cwd);
    while let Some(d) = dir {
        if markers.iter().any(|m| !m.is_empty() && d.join(m).exists()) {
            return Some(d.to_path_buf());
        }
        dir = d.parent();
    }
    None
}

/// A config file: a set of named profiles (the analog of Codex `-p/--profile`).
/// This is the **SDK/embedder** config surface (JSON, via
/// [`Config::from_profile_file`]). BP-9 gave the same named-bundle mechanism
/// a launch-time selector on the CLI side: `supercode --profile <name>`
/// selects a `[profiles.<name>]` bundle out of the user's TOML
/// `config.toml` (`userconfig::FileConfig`), applied as its own layer
/// between the user layer and the project layer (cx§6's
/// `user → profile → project` order).
#[derive(Debug, Clone, Default, serde::Deserialize)]
pub struct ConfigFile {
    /// Profiles keyed by name.
    #[serde(default)]
    pub profiles: HashMap<String, ConfigProfile>,
}

impl Config {
    /// Load a named profile from a JSON config file into a builder. Layered:
    /// start from defaults, then apply the named profile's set fields.
    pub fn from_profile_file(
        path: impl AsRef<std::path::Path>,
        profile: &str,
    ) -> crate::Result<ConfigBuilder> {
        let text = std::fs::read_to_string(path.as_ref())?;
        let file: ConfigFile = serde_json::from_str(&text).map_err(crate::Error::Decode)?;
        let p = file
            .profiles
            .get(profile)
            .ok_or_else(|| crate::Error::Other(format!("no profile `{profile}` in config file")))?;
        Ok(ConfigBuilder::default().apply_profile(p))
    }
}

impl ConfigBuilder {
    /// Apply the set fields of a [`ConfigProfile`] over the current builder.
    pub fn apply_profile(mut self, p: &ConfigProfile) -> Self {
        if let Some(m) = &p.model {
            self.config.model = m.clone();
        }
        if let Some(u) = &p.base_url {
            self.config.base_url = u.clone();
        }
        if let Some(s) = &p.system_prompt {
            self.config.system_prompt = s.clone();
        }
        if let Some(extra) = &p.append_system_prompt {
            // P4 (§3.1 `core.append_system_prompt`): additive, composed onto
            // whatever `system_prompt` is on the builder AT THIS POINT —
            // either the value just applied above, or whatever the caller
            // already set/left at its `Config::default()` — never a
            // replacement. This intentionally runs regardless of whether
            // `p.system_prompt` was set, so an append-only profile still
            // composes onto the existing base.
            self.config.system_prompt = format!("{}\n\n{extra}", self.config.system_prompt);
        }
        self.config.temperature = p.temperature.or(self.config.temperature);
        self.config.max_tokens = p.max_tokens.or(self.config.max_tokens);
        if p.effort.is_some() {
            self.config.effort = p.effort.clone();
        }
        if let Some(sb) = &p.sandbox {
            // Fail *safe*: an unrecognized value (typo, future variant) must not
            // silently grant full filesystem access. Only the explicit
            // danger string opts out of confinement.
            self.config.sandbox = match sb.as_str() {
                "read_only" | "read-only" | "readonly" => crate::tools::SandboxPolicy::ReadOnly,
                "workspace_write" | "workspace-write" => {
                    crate::tools::SandboxPolicy::WorkspaceWrite
                }
                "danger_full_access" | "danger-full-access" => {
                    crate::tools::SandboxPolicy::DangerFullAccess
                }
                other => {
                    tracing::warn!(
                        "unknown sandbox policy `{other}` in profile; defaulting to read_only"
                    );
                    crate::tools::SandboxPolicy::ReadOnly
                }
            };
        }
        if let Some(ap) = &p.approval {
            // Fail safe: an unrecognized value defaults to the most-prompting
            // policy, never to `never`.
            self.config.approval = match ap.as_str() {
                "on_request" | "on-request" => ApprovalPolicy::OnRequest,
                "untrusted" => ApprovalPolicy::Untrusted,
                "never" => ApprovalPolicy::Never,
                // P5-1 (§3.2 S8): cx-parity's real intended posture — see
                // `ApprovalPolicy::ModelRequested`'s doc comment.
                "model_requested" | "model-requested" => ApprovalPolicy::ModelRequested,
                other => {
                    tracing::warn!(
                        "unknown approval policy `{other}` in profile; defaulting to untrusted"
                    );
                    ApprovalPolicy::Untrusted
                }
            };
        }
        if let Some(pc) = p.project_context {
            self.config.load_project_context = pc;
        }
        if let Some(env) = &p.api_key_env {
            self.config.api_key_env = env.clone();
        }
        if let Some(cmd) = &p.api_key_cmd {
            self.config.api_key_cmd = Some(cmd.clone());
        }
        if let Some(argv) = &p.api_key_command {
            self.config.api_key_command = Some(argv.clone());
        }
        if let Some(v) = p.update_check {
            self.config.update_check = v;
        }
        // Scalars replace (§3.3).
        if let Some(n) = p.max_iterations {
            self.config.max_iterations = n;
        }
        // Arrays replace wholesale (§3.3), not append — predictable overlay.
        if let Some(dirs) = &p.additional_dirs {
            self.config.additional_dirs = dirs.iter().map(std::path::PathBuf::from).collect();
        }
        if let Some(n) = p.compact_after_messages {
            self.config.compact_after_messages = Some(n);
        }
        if let Some(plan) = &p.cache_plan {
            // Fail safe: an unrecognized value never silently opts into
            // caching behavior the operator didn't ask for.
            self.config.cache_plan = match plan.as_str() {
                "off" => CachePlan::Off,
                "imported_prefix" | "imported-prefix" => CachePlan::ImportedPrefix,
                other => {
                    tracing::warn!("unknown cache plan `{other}` in profile; defaulting to off");
                    CachePlan::Off
                }
            };
        }
        if let Some(v) = p.cache_warnings {
            self.config.cache_warnings = v;
        }
        if p.tool_advertising.is_some() || p.tool_advertising_core.is_some() {
            // F6 fix: per-key replace (§3.3) — neither key alone may clobber
            // the other's current value. Compute the effective core list
            // FIRST (the profile's new value if given, else whatever's
            // already active) so an explicit `"deferred"` mode with no
            // `_core` doesn't wipe an existing list, then only change the
            // MODE if the profile actually set one — setting `_core` alone
            // must not silently reset the mode to `Full` (which previously
            // discarded the array outright, since `Full` ignores it).
            let existing_core = match &self.config.tool_advertising {
                ToolAdvertising::Deferred { core } => core.clone(),
                ToolAdvertising::Full => Vec::new(),
            };
            let core = p.tool_advertising_core.clone().unwrap_or(existing_core);
            self.config.tool_advertising = match p.tool_advertising.as_deref() {
                Some("deferred") => ToolAdvertising::Deferred { core },
                Some("full") => ToolAdvertising::Full,
                Some(other) => {
                    tracing::warn!(
                        "unknown tool_advertising mode `{other}` in profile; defaulting to full"
                    );
                    ToolAdvertising::Full
                }
                None => match &self.config.tool_advertising {
                    // Mode untouched — only refresh the core list if
                    // already `Deferred` (`Full` has nowhere to put one).
                    ToolAdvertising::Deferred { .. } => ToolAdvertising::Deferred { core },
                    ToolAdvertising::Full => ToolAdvertising::Full,
                },
            };
        }
        if let Some(tier) = &p.schema_tier {
            // Fail safe: unrecognized value keeps the verbose (never
            // under-informative) default rather than guessing a shrink tier.
            self.config.tool_schema_tier =
                crate::tools::SchemaTier::parse(tier).unwrap_or_else(|| {
                    tracing::warn!("unknown schema tier `{tier}` in profile; defaulting to full");
                    crate::tools::SchemaTier::Full
                });
        }
        // Arrays replace wholesale (§3.3).
        if let Some(tools) = &p.auto_approved_tools {
            self.config.auto_approved_tools = tools.iter().cloned().collect();
        }
        if let Some(patterns) = &p.tool_deny_patterns {
            self.config.tool_deny_patterns = patterns.clone();
        }
        if let Some(patterns) = &p.tool_allow_patterns {
            self.config.tool_allow_patterns = patterns.clone();
        }
        // Tables merge key-wise (§3.3), not wholesale replace.
        if let Some(headers) = &p.extra_headers {
            for (k, v) in headers {
                self.config.extra_headers.insert(k.clone(), v.clone());
            }
        }
        if let Some(body) = &p.extra_body {
            for (k, v) in body {
                self.config.extra_body.insert(k.clone(), v.clone());
            }
        }
        if let Some(n) = p.max_tool_output_bytes {
            self.config.max_tool_output_bytes = Some(n);
        }
        if let Some(n) = p.max_total_output_tokens {
            self.config.max_total_output_tokens = Some(n);
        }
        if let Some(n) = p.max_budget_usd {
            self.config.max_budget_usd = Some(n);
        }
        if let Some(n) = p.max_steps {
            self.config.max_steps = Some(n);
        }
        if let Some(n) = p.price_input_per_mtok {
            self.config.price_input_per_mtok = Some(n);
        }
        if let Some(n) = p.price_output_per_mtok {
            self.config.price_output_per_mtok = Some(n);
        }
        if let Some(prompts) = &p.prompts {
            for (k, v) in prompts {
                self.config.prompts.insert(k.clone(), v.clone());
            }
        }
        if let Some(overrides) = &p.tool_overrides {
            for (name, o) in overrides {
                let entry = self.config.tool_overrides.entry(name.clone()).or_default();
                if let Some(en) = o.enabled {
                    entry.enabled = Some(en);
                }
                if let Some(desc) = &o.description {
                    entry.description = Some(desc.clone());
                }
                if let Some(tier) = &o.schema_tier {
                    entry.schema_tier = Some(crate::tools::SchemaTier::parse(tier).unwrap_or_else(|| {
                        tracing::warn!(
                            "unknown schema tier `{tier}` in tool override `{name}`; defaulting to full"
                        );
                        crate::tools::SchemaTier::Full
                    }));
                }
                if let Some(t) = o.timeout_secs {
                    entry.timeout_secs = Some(t);
                }
            }
        }
        // P4b: scalars replace (S3.3).
        if let Some(v) = p.env_context {
            self.config.env_context = v;
        }
        if let Some(v) = &p.project_root_markers {
            self.config.project_root_markers = v.clone();
        }
        if let Some(v) = p.project_doc_max_bytes {
            self.config.project_doc_max_bytes = Some(v);
        }
        if let Some(v) = &p.project_doc_excludes {
            self.config.project_doc_excludes = v.clone();
        }
        if let Some(v) = p.project_doc_strip_comments {
            self.config.project_doc_strip_comments = v;
        }
        if let Some(v) = p.instruction_imports {
            self.config.instruction_imports = v;
        }
        if let Some(v) = p.retry_enabled {
            self.config.retry_enabled = v;
        }
        if let Some(v) = p.retry_max_retries {
            self.config.retry_max_retries = Some(v);
        }
        if let Some(v) = p.retry_base_delay_ms {
            self.config.retry_base_delay_ms = Some(v);
        }
        if let Some(v) = p.compaction_reserve_tokens {
            self.config.compaction_reserve_tokens = Some(v);
        }
        if let Some(v) = p.compaction_keep_recent_tokens {
            self.config.compaction_keep_recent_tokens = Some(v);
        }
        if let Some(v) = &p.compaction_focus_instructions {
            self.config.compaction_focus_instructions = Some(v.clone());
        }
        if let Some(v) = p.auto_title {
            self.config.auto_title = v;
        }
        if let Some(mode) = &p.steering_mode {
            // Fail safe: an unrecognized value keeps the current setting
            // rather than guessing.
            match SteeringMode::parse(mode) {
                Some(m) => self.config.steering_mode = m,
                None => tracing::warn!("unknown steering_mode `{mode}` in profile; ignoring"),
            }
        }
        if let Some(mode) = &p.follow_up_mode {
            match SteeringMode::parse(mode) {
                Some(m) => self.config.follow_up_mode = m,
                None => tracing::warn!("unknown follow_up_mode `{mode}` in profile; ignoring"),
            }
        }
        // P4c: scalars replace (S3.3).
        if let Some(v) = p.read_file_multimodal {
            self.config.read_file_multimodal = v;
        }
        // BP-2: `cat -n` gutter + recoverable tool-output spill (S3.3).
        if let Some(v) = p.read_file_line_numbers {
            self.config.read_file_line_numbers = v;
        }
        if let Some(v) = p.tool_output_spill {
            self.config.tool_output_spill = v;
        }
        if let Some(v) = p.edit_file_require_read_before_edit {
            self.config.edit_file_require_read_before_edit = v;
        }
        if let Some(v) = p.edit_file_notebook_aware {
            self.config.edit_file_notebook_aware = v;
        }
        if let Some(v) = p.shell_env_snapshot {
            self.config.shell_env_snapshot = v;
        }
        if let Some(v) = p.doom_loop_threshold {
            self.config.doom_loop_threshold = Some(v);
        }
        if let Some(v) = p.nested_instructions {
            self.config.nested_instructions = v;
        }
        if let Some(v) = p.model_switch_notice {
            self.config.model_switch_notice = v;
        }
        if let Some(v) = p.model_switch_allow_switch {
            self.config.model_switch_allow_switch = v;
        }
        // P4e: scalars replace (S3.3).
        if let Some(v) = p.context_injections {
            self.config.context_injections = v;
        }
        if let Some(v) = p.compaction_enabled {
            self.config.compaction_enabled = v;
        }
        if let Some(v) = p.compaction_summarize {
            self.config.compaction_summarize = v;
        }
        if let Some(v) = p.parallel_tool_calls {
            self.config.parallel_tool_calls = v;
        }
        if let Some(v) = p.session_git_metadata {
            self.config.session_git_metadata = v;
        }
        if let Some(v) = &p.session_dir {
            self.config.session_dir = Some(v.clone());
        }
        if let Some(v) = p.session_append_only {
            self.config.session_append_only = v;
        }
        if let Some(v) = p.session_queue_persist {
            self.config.session_queue_persist = v;
        }
        if let Some(v) = p.session_persist {
            self.config.session_persist = v;
        }
        if let Some(v) = &p.session_name {
            self.config.session_name = Some(v.clone());
        }
        if let Some(v) = p.session_retention_days {
            self.config.session_retention_days = Some(v);
        }
        if let Some(fmt) = &p.session_export_format {
            match crate::human_export::HumanExportFormat::parse(fmt) {
                Some(f) => self.config.session_export_format = f,
                None => {
                    tracing::warn!("unknown session export_format `{fmt}` in profile; ignoring")
                }
            }
        }
        self
    }
}

/// Fluent builder for [`Config`].
#[derive(Default)]
pub struct ConfigBuilder {
    config: Config,
}

impl 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 from_config(config: Config) -> Self {
        ConfigBuilder { config }
    }

    /// Set the model identifier.
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.config.model = model.into();
        self
    }

    /// Set the OpenAI-compatible base URL (defaults to OpenRouter).
    pub fn base_url(mut self, url: impl Into<String>) -> Self {
        self.config.base_url = url.into();
        self
    }

    /// Provide the API key explicitly.
    pub fn api_key(mut self, key: impl Into<String>) -> Self {
        self.config.api_key = Some(key.into());
        self
    }

    /// Change which environment variable the key is read from.
    pub fn api_key_env(mut self, var: impl Into<String>) -> Self {
        self.config.api_key_env = var.into();
        self
    }

    /// Set the credential-helper command — see [`Config::api_key_cmd`].
    pub fn api_key_cmd(mut self, cmd: impl Into<String>) -> Self {
        self.config.api_key_cmd = Some(cmd.into());
        self
    }

    /// Set the argv credential helper — see [`Config::api_key_command`].
    pub fn api_key_command(mut self, argv: Vec<String>) -> Self {
        self.config.api_key_command = Some(argv);
        self
    }

    /// Enable/disable the startup release check — see
    /// [`Config::update_check`].
    pub fn update_check(mut self, on: bool) -> Self {
        self.config.update_check = on;
        self
    }

    /// Replace the system prompt.
    pub fn system_prompt(mut self, prompt: impl Into<String>) -> Self {
        self.config.system_prompt = prompt.into();
        self
    }

    /// Set the sampling temperature.
    pub fn temperature(mut self, t: f32) -> Self {
        self.config.temperature = Some(t);
        self
    }

    /// Set the max output tokens.
    pub fn max_tokens(mut self, n: u32) -> Self {
        self.config.max_tokens = Some(n);
        self
    }

    /// Set the per-`send` iteration budget.
    pub fn max_iterations(mut self, n: usize) -> Self {
        self.config.max_iterations = n;
        self
    }

    /// Set the reasoning/effort level (`reasoning_effort`).
    pub fn effort(mut self, level: impl Into<String>) -> Self {
        self.config.effort = Some(level.into());
        self
    }

    /// Constrain output to a JSON schema (`response_format`).
    pub fn response_format(mut self, format: serde_json::Value) -> Self {
        self.config.response_format = Some(format);
        self
    }

    /// Merge an extra request-body field (provider-native passthrough).
    pub fn extra_body_field(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
        self.config.extra_body.insert(key.into(), value);
        self
    }

    /// 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_tool_output_bytes(mut self, n: usize) -> Self {
        self.config.max_tool_output_bytes = Some(n);
        self
    }

    /// 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 max_total_output_tokens(mut self, n: u64) -> Self {
        self.config.max_total_output_tokens = Some(n);
        self
    }

    /// BP-7 — see [`Config::max_budget_usd`].
    pub fn max_budget_usd(mut self, usd: f64) -> Self {
        self.config.max_budget_usd = Some(usd);
        self
    }

    /// BP-7 — see [`Config::max_steps`].
    pub fn max_steps(mut self, n: usize) -> Self {
        self.config.max_steps = Some(n);
        self
    }

    /// BP-7 — see [`Config::price_input_per_mtok`] /
    /// [`Config::price_output_per_mtok`]. Both halves at once, because
    /// half a price bills the other half at zero.
    pub fn model_price(mut self, input_per_mtok: f64, output_per_mtok: f64) -> Self {
        self.config.price_input_per_mtok = Some(input_per_mtok);
        self.config.price_output_per_mtok = Some(output_per_mtok);
        self
    }

    /// Set the working directory tools operate in.
    pub fn cwd(mut self, dir: impl Into<PathBuf>) -> Self {
        self.config.cwd = dir.into();
        self
    }

    /// Add an extra root directory (`--add-dir` / multi-root / worktree).
    pub fn add_dir(mut self, dir: impl Into<PathBuf>) -> Self {
        self.config.additional_dirs.push(dir.into());
        self
    }

    /// Enable auto-loading of `CLAUDE.md` / `AGENTS.md` into the system prompt.
    pub fn project_context(mut self, enabled: bool) -> Self {
        self.config.load_project_context = enabled;
        self
    }

    /// Register a named prompt template (skill / slash command).
    pub fn prompt(mut self, name: impl Into<String>, template: impl Into<String>) -> Self {
        self.config.prompts.insert(name.into(), template.into());
        self
    }

    /// Compact the conversation once it exceeds `n` messages.
    pub fn compact_after_messages(mut self, n: usize) -> Self {
        self.config.compact_after_messages = Some(n);
        self
    }

    /// Set the filesystem sandbox policy for write-capable tools.
    pub fn sandbox(mut self, policy: crate::tools::SandboxPolicy) -> Self {
        self.config.sandbox = policy;
        self
    }

    /// Set the tool-approval policy.
    pub fn approval(mut self, policy: ApprovalPolicy) -> Self {
        self.config.approval = policy;
        self
    }

    /// Add a tool to the auto-approve allowlist (no approval under `OnRequest`).
    pub fn auto_approve_tool(mut self, name: impl Into<String>) -> Self {
        self.config.auto_approved_tools.insert(name.into());
        self
    }

    /// P4: add a glob pattern to [`Config::tool_deny_patterns`] — a match
    /// forces approval unconditionally, even under `ApprovalPolicy::Never`.
    pub fn deny_tool_pattern(mut self, pattern: impl Into<String>) -> Self {
        self.config.tool_deny_patterns.push(pattern.into());
        self
    }

    /// P4: add a glob pattern to [`Config::tool_allow_patterns`] — the
    /// pattern generalization of [`Self::auto_approve_tool`].
    pub fn allow_tool_pattern(mut self, pattern: impl Into<String>) -> Self {
        self.config.tool_allow_patterns.push(pattern.into());
        self
    }

    /// Set the handler consulted when a tool call needs approval.
    pub fn approval_handler(mut self, handler: ApprovalHandler) -> Self {
        self.config.approval_handler = Some(handler);
        self
    }

    /// Set the pre-tool hook (may block a call by returning `Some(reason)`).
    pub fn pre_tool_hook(mut self, hook: PreToolHook) -> Self {
        self.config.pre_tool_hook = Some(hook);
        self
    }

    /// Set the post-tool hook (observational).
    pub fn post_tool_hook(mut self, hook: PostToolHook) -> Self {
        self.config.post_tool_hook = Some(hook);
        self
    }

    /// Disable a tool by name.
    pub fn disable_tool(mut self, name: impl Into<String>) -> Self {
        self.config
            .tool_overrides
            .entry(name.into())
            .or_default()
            .enabled = Some(false);
        self
    }

    /// Enable a tool by name (overriding a prior disable).
    pub fn enable_tool(mut self, name: impl Into<String>) -> Self {
        self.config
            .tool_overrides
            .entry(name.into())
            .or_default()
            .enabled = Some(true);
        self
    }

    /// Override the description the model sees for a tool.
    pub fn tool_description(
        mut self,
        name: impl Into<String>,
        description: impl Into<String>,
    ) -> Self {
        self.config
            .tool_overrides
            .entry(name.into())
            .or_default()
            .description = Some(description.into());
        self
    }

    /// Set how tools are advertised to the model (B6).
    pub fn tool_advertising(mut self, advertising: ToolAdvertising) -> Self {
        self.config.tool_advertising = advertising;
        self
    }

    /// 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 schema_tier(mut self, tier: crate::tools::SchemaTier) -> Self {
        self.config.tool_schema_tier = tier;
        self
    }

    /// 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 tool_schema_tier(
        mut self,
        name: impl Into<String>,
        tier: crate::tools::SchemaTier,
    ) -> Self {
        self.config
            .tool_overrides
            .entry(name.into())
            .or_default()
            .schema_tier = Some(tier);
        self
    }

    /// Add an extra HTTP header sent on every request.
    pub fn header(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.config.extra_headers.insert(key.into(), value.into());
        self
    }

    /// Attach a streaming event sink.
    pub fn event_sink(mut self, sink: EventSink) -> Self {
        self.config.event_sink = Some(sink);
        self
    }

    /// Set the prompt-caching plan (B7).
    pub fn cache_plan(mut self, plan: CachePlan) -> Self {
        self.config.cache_plan = plan;
        self
    }

    /// UX-26 (B7-warn): enable/disable the cache-cold warning (default on).
    pub fn cache_warnings(mut self, enabled: bool) -> Self {
        self.config.cache_warnings = enabled;
        self
    }

    /// P3: turn on the `[experimental] module_registry` gate — see
    /// [`Config::module_registry`].
    pub fn module_registry(mut self, enabled: bool) -> Self {
        self.config.module_registry = enabled;
        self
    }

    /// P3: set the resolved module-activation set — see
    /// [`Config::module_activation`].
    pub fn module_activation(mut self, activation: crate::modules::ModuleActivation) -> Self {
        self.config.module_activation = activation;
        self
    }

    /// P3: set the effective `[core.tools] enabled` list — see
    /// [`Config::core_tools_enabled`].
    pub fn core_tools_enabled(mut self, tools: Vec<String>) -> Self {
        self.config.core_tools_enabled = tools;
        self
    }

    /// P3: set `[core.skills].enabled` — see [`Config::skills_enabled`].
    pub fn skills_enabled(mut self, enabled: bool) -> Self {
        self.config.skills_enabled = enabled;
        self
    }

    /// BP-6: set `[core.skills].harness` — see [`Config::skills_harness`].
    pub fn skills_harness(mut self, harness: impl Into<String>) -> Self {
        self.config.skills_harness = Some(harness.into());
        self
    }

    /// BP-6: set `[core.skills].dirs` — see [`Config::skills_dirs`].
    pub fn skills_dirs(mut self, dirs: Vec<std::path::PathBuf>) -> Self {
        self.config.skills_dirs = dirs;
        self
    }

    /// BP-6: set `[core.skills].implicit_match` — see
    /// [`Config::skills_implicit_match`].
    pub fn skills_implicit_match(mut self, enabled: bool) -> Self {
        self.config.skills_implicit_match = enabled;
        self
    }

    /// BP-5: set `[core.skills].shell_injection` — see
    /// [`Config::skills_shell_injection`].
    pub fn skills_shell_injection(mut self, enabled: bool) -> Self {
        self.config.skills_shell_injection = enabled;
        self
    }

    /// BP-5: set `[core.file_mentions]` — see [`Config::file_mentions`].
    pub fn file_mentions(mut self, enabled: bool) -> Self {
        self.config.file_mentions = enabled;
        self
    }

    /// BP-5: set `[core.output_style]` — see [`Config::output_style`].
    pub fn output_style(mut self, name: impl Into<String>) -> Self {
        self.config.output_style = name.into();
        self
    }

    /// BP-5: set `[core.path_rules]` — see [`Config::path_rules`].
    pub fn path_rules(mut self, enabled: bool) -> Self {
        self.config.path_rules = enabled;
        self
    }

    /// BP-5: set `[capabilities.model_catalog].base_prompts` — see
    /// [`Config::model_family_prompts`].
    pub fn model_family_prompts(
        mut self,
        prompts: std::collections::BTreeMap<String, String>,
    ) -> Self {
        self.config.model_family_prompts = prompts;
        self
    }

    /// P4: set the small/utility model id — see `Config::small_model`.
    pub fn small_model(mut self, model: impl Into<String>) -> Self {
        self.config.small_model = Some(model.into());
        self
    }

    /// BP-13: set the resolved model-routing table — see
    /// `Config::model_routing`.
    pub fn model_routing(mut self, routing: crate::model_catalog::Routing) -> Self {
        self.config.model_routing = routing;
        self
    }

    /// BP-13: set the session-level service tier (`/fast`) — see
    /// `Config::service_tier`.
    pub fn service_tier(mut self, tier: impl Into<String>) -> Self {
        self.config.service_tier = Some(tier.into());
        self
    }

    /// P4: set the model failure-fallback chain — see `Config::model_fallback`.
    pub fn model_fallback(mut self, chain: Vec<String>) -> Self {
        self.config.model_fallback = chain;
        self
    }

    /// P4b: turn on the environment-context block — see [`Config::env_context`].
    pub fn env_context(mut self, enabled: bool) -> Self {
        self.config.env_context = enabled;
        self
    }

    /// P4b: set the project-root marker filenames — see
    /// [`Config::project_root_markers`].
    pub fn project_root_markers(mut self, markers: Vec<String>) -> Self {
        self.config.project_root_markers = markers;
        self
    }

    /// P4b: cap the total bytes of assembled instruction-file content — see
    /// [`Config::project_doc_max_bytes`].
    pub fn project_doc_max_bytes(mut self, n: usize) -> Self {
        self.config.project_doc_max_bytes = Some(n);
        self
    }

    /// P4b: turn on `@path` instruction imports — see
    /// [`Config::instruction_imports`].
    pub fn instruction_imports(mut self, enabled: bool) -> Self {
        self.config.instruction_imports = enabled;
        self
    }

    /// 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 retry(
        mut self,
        enabled: bool,
        max_retries: Option<u32>,
        base_delay_ms: Option<u64>,
    ) -> Self {
        self.config.retry_enabled = enabled;
        self.config.retry_max_retries = max_retries;
        self.config.retry_base_delay_ms = base_delay_ms;
        self
    }

    /// P4b: turn on the compaction token-pressure trigger — see
    /// [`Config::compaction_reserve_tokens`].
    pub fn compaction_pressure(mut self, reserve_tokens: u64, keep_recent_tokens: u64) -> Self {
        self.config.compaction_reserve_tokens = Some(reserve_tokens);
        self.config.compaction_keep_recent_tokens = Some(keep_recent_tokens);
        self
    }

    /// P4b: set the compaction focus instructions — see
    /// [`Config::compaction_focus_instructions`].
    pub fn compaction_focus_instructions(mut self, text: impl Into<String>) -> Self {
        self.config.compaction_focus_instructions = Some(text.into());
        self
    }

    /// P4b: turn on the auto-title gate — see [`Config::auto_title`].
    pub fn auto_title(mut self, enabled: bool) -> Self {
        self.config.auto_title = enabled;
        self
    }

    /// P4b: set the mid-turn steering delivery mode — see
    /// [`Config::steering_mode`].
    pub fn steering_mode(mut self, mode: SteeringMode) -> Self {
        self.config.steering_mode = mode;
        self
    }

    /// P4b: set the idle follow-up delivery mode — see
    /// [`Config::follow_up_mode`].
    pub fn follow_up_mode(mut self, mode: SteeringMode) -> Self {
        self.config.follow_up_mode = mode;
        self
    }

    /// P4b: install a stop-gate hook — see [`Config::stop_gate`].
    pub fn stop_gate(mut self, hook: StopGateHook) -> Self {
        self.config.stop_gate = Some(hook);
        self
    }

    /// BP-2: number `read_file` output `cat -n` style — see
    /// [`Config::read_file_line_numbers`].
    pub fn read_file_line_numbers(mut self, enabled: bool) -> Self {
        self.config.read_file_line_numbers = enabled;
        self
    }

    /// BP-2: spill capped tool output to a per-session file the model can
    /// read back — see [`Config::tool_output_spill`].
    pub fn tool_output_spill(mut self, enabled: bool) -> Self {
        self.config.tool_output_spill = enabled;
        self
    }

    /// P4c: turn on multimodal `read_file` — see [`Config::read_file_multimodal`].
    pub fn read_file_multimodal(mut self, enabled: bool) -> Self {
        self.config.read_file_multimodal = enabled;
        self
    }

    /// P4c: require a prior read before `edit_file` accepts an edit — see
    /// [`Config::edit_file_require_read_before_edit`].
    pub fn edit_file_require_read_before_edit(mut self, enabled: bool) -> Self {
        self.config.edit_file_require_read_before_edit = enabled;
        self
    }

    /// P4c: turn on notebook-cell-aware `edit_file` — see
    /// [`Config::edit_file_notebook_aware`].
    pub fn edit_file_notebook_aware(mut self, enabled: bool) -> Self {
        self.config.edit_file_notebook_aware = enabled;
        self
    }

    /// P4c: turn on shell-environment snapshotting — see
    /// [`Config::shell_env_snapshot`].
    pub fn shell_env_snapshot(mut self, enabled: bool) -> Self {
        self.config.shell_env_snapshot = enabled;
        self
    }

    /// P4c: set the doom-loop repetition threshold — see
    /// [`Config::doom_loop_threshold`].
    pub fn doom_loop_threshold(mut self, n: u32) -> Self {
        self.config.doom_loop_threshold = Some(n);
        self
    }

    /// P4c: turn on on-demand nested instruction loading — see
    /// [`Config::nested_instructions`].
    pub fn nested_instructions(mut self, enabled: bool) -> Self {
        self.config.nested_instructions = enabled;
        self
    }

    /// P4c: turn on mid-session model switch's persisted-record +
    /// reasoning-filter behavior — see [`Config::model_switch_allow_switch`].
    pub fn model_switch_allow_switch(mut self, enabled: bool) -> Self {
        self.config.model_switch_allow_switch = enabled;
        self
    }

    /// BP-13: inject a switch notice on a mid-session model change — see
    /// [`Config::model_switch_notice`].
    pub fn model_switch_notice(mut self, enabled: bool) -> Self {
        self.config.model_switch_notice = enabled;
        self
    }

    /// BP-13: set the effort level plan mode runs at — see
    /// [`Config::plan_mode_effort`].
    pub fn plan_mode_effort(mut self, effort: impl Into<String>) -> Self {
        self.config.plan_mode_effort = Some(effort.into());
        self
    }

    /// P4e: turn on ambient context-injection blocks — see
    /// [`Config::context_injections`].
    pub fn context_injections(mut self, enabled: bool) -> Self {
        self.config.context_injections = enabled;
        self
    }

    /// P4e: append one named ambient context block — see
    /// [`Config::context_injection_blocks`].
    pub fn context_injection_block(
        mut self,
        name: impl Into<String>,
        content: impl Into<String>,
    ) -> Self {
        self.config
            .context_injection_blocks
            .push(ContextInjectionBlock::new(name, content));
        self
    }

    /// P4e: master gate for all auto-compaction — see
    /// [`Config::compaction_enabled`].
    pub fn compaction_enabled(mut self, enabled: bool) -> Self {
        self.config.compaction_enabled = enabled;
        self
    }

    /// P4e: run independent tool calls concurrently — see
    /// [`Config::parallel_tool_calls`].
    pub fn parallel_tool_calls(mut self, enabled: bool) -> Self {
        self.config.parallel_tool_calls = enabled;
        self
    }

    /// P4e: capture git branch/sha/dirty at construction — see
    /// [`Config::session_git_metadata`].
    pub fn session_git_metadata(mut self, enabled: bool) -> Self {
        self.config.session_git_metadata = enabled;
        self
    }

    /// P4e DEFECT-FIX: ephemeral vs. persisted session gate — see
    /// [`Config::session_persist`].
    pub fn session_persist(mut self, enabled: bool) -> Self {
        self.config.session_persist = enabled;
        self
    }

    /// BP-8: arm the append-only session journal — see
    /// [`Config::session_append_only`].
    pub fn session_append_only(mut self, enabled: bool) -> Self {
        self.config.session_append_only = enabled;
        self
    }

    /// BP-8: record pending inputs as journal queue operations — see
    /// [`Config::session_queue_persist`].
    pub fn session_queue_persist(mut self, enabled: bool) -> Self {
        self.config.session_queue_persist = enabled;
        self
    }

    /// BP-8: persist the `update_plan` checklist with the session — see
    /// [`Config::todos_persist`].
    pub fn todos_persist(mut self, enabled: bool) -> Self {
        self.config.todos_persist = enabled;
        self
    }

    /// P4e DEFECT-FIX: a caller-configured session name — see
    /// [`Config::session_name`].
    pub fn session_name(mut self, name: impl Into<String>) -> Self {
        self.config.session_name = Some(name.into());
        self
    }

    /// P5-3 (§3.1 `capabilities.subagents.enabled`) — see
    /// [`Config::subagents_enabled`].
    pub fn subagents_enabled(mut self, enabled: bool) -> Self {
        self.config.subagents_enabled = enabled;
        self
    }

    /// P5-3 (§3.1 `capabilities.subagents.max_depth`) — see
    /// [`Config::subagents_max_depth`].
    pub fn subagents_max_depth(mut self, n: usize) -> Self {
        self.config.subagents_max_depth = n;
        self
    }

    /// P5-3 (resource bound) — see [`Config::subagents_max_concurrent`].
    pub fn subagents_max_concurrent(mut self, n: usize) -> Self {
        self.config.subagents_max_concurrent = n;
        self
    }

    /// P5-3 (§3.1 `capabilities.subagents.background`) — see
    /// [`Config::subagents_background`].
    pub fn subagents_background(mut self, enabled: bool) -> Self {
        self.config.subagents_background = enabled;
        self
    }

    /// P5-3 (§2.2 C6) — see [`Config::subagents_background_prompts`].
    pub fn subagents_background_prompts(
        mut self,
        policy: crate::subagents::BackgroundPromptsPolicy,
    ) -> Self {
        self.config.subagents_background_prompts = Some(policy);
        self
    }

    /// Enable Claude Code's `Agent` compatibility alias for named subagents.
    pub fn subagents_claude_agent_alias(mut self, enabled: bool) -> Self {
        self.config.subagents_claude_agent_alias = enabled;
        self
    }

    /// Enable Claude's paused runtime-state compatibility intrinsics.
    pub fn claude_runtime_tools_enabled(mut self, enabled: bool) -> Self {
        self.config.claude_runtime_tools_enabled = enabled;
        self
    }

    /// P5-3 (§3.1 `capabilities.subagents.agents.<name>`) — register one
    /// named agent definition, keyed by [`crate::subagents::NamedAgentDefinition::name`].
    pub fn subagent_definition(mut self, def: crate::subagents::NamedAgentDefinition) -> Self {
        self.config
            .subagents_definitions
            .insert(def.name.clone(), def);
        self
    }

    /// 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 subagent_depth(mut self, depth: usize) -> Self {
        self.config.subagent_depth = depth;
        self
    }

    /// P5-6 (§3.1 `capabilities.tools_background.enabled`) — see
    /// [`Config::tools_background_enabled`].
    pub fn tools_background_enabled(mut self, enabled: bool) -> Self {
        self.config.tools_background_enabled = enabled;
        self
    }

    /// P5-6 (resource bound) — see [`Config::tools_background_max_concurrent`].
    pub fn tools_background_max_concurrent(mut self, n: usize) -> Self {
        self.config.tools_background_max_concurrent = n;
        self
    }

    /// P5-6 (resource bound) — see [`Config::tools_background_max_output_bytes`].
    pub fn tools_background_max_output_bytes(mut self, n: usize) -> Self {
        self.config.tools_background_max_output_bytes = n;
        self
    }

    /// P5-9 (§3.1 `capabilities.checkpoint.enabled`) — see
    /// [`Config::checkpoint_enabled`].
    pub fn checkpoint_enabled(mut self, enabled: bool) -> Self {
        self.config.checkpoint_enabled = enabled;
        self
    }

    /// P5-9 (bounded-disk requirement) — see [`Config::checkpoint_retain`].
    pub fn checkpoint_retain(mut self, n: usize) -> Self {
        self.config.checkpoint_retain = n;
        self
    }

    /// BP-10 — see [`Config::trust_handler`]. Installing the door is what
    /// turns `[capabilities.trust] default = "ask"` from "behaves like
    /// never" into a real question.
    pub fn trust_handler(
        mut self,
        handler: std::sync::Arc<dyn crate::permissions::PermissionsApprovalHandler>,
    ) -> Self {
        self.config.trust_handler = Some(handler);
        self
    }

    /// BP-10 (embedder/test override) — see [`Config::trust_store`].
    pub fn trust_store(mut self, path: impl Into<PathBuf>) -> Self {
        self.config.trust_store = Some(path.into());
        self
    }

    /// BP-10 — see [`Config::permissions_approvals_persist`]. Turning this
    /// on WITHOUT also setting [`Self::permissions_approval_store`] uses
    /// the per-project default under `$SUPERCODE_HOME`.
    pub fn permissions_approvals_persist(mut self, persist: bool) -> Self {
        self.config.permissions_approvals_persist = persist;
        self
    }

    /// BP-10 (embedder/test override) — see
    /// [`Config::permissions_approval_store`].
    pub fn permissions_approval_store(mut self, path: impl Into<PathBuf>) -> Self {
        self.config.permissions_approval_store = Some(path.into());
        self
    }

    /// P5-9 (embedder/test override) — see [`Config::checkpoint_dir`].
    pub fn checkpoint_dir(mut self, dir: impl Into<PathBuf>) -> Self {
        self.config.checkpoint_dir = Some(dir.into());
        self
    }

    /// P5-11 (§3.1 `capabilities.lsp.enabled`) — see [`Config::lsp_enabled`].
    pub fn lsp_enabled(mut self, enabled: bool) -> Self {
        self.config.lsp_enabled = enabled;
        self
    }

    /// P5-11 (`capabilities.lsp.servers`) — see [`Config::lsp_servers`].
    pub fn lsp_servers(mut self, servers: Vec<(String, crate::lsp::LspServerSpec)>) -> Self {
        self.config.lsp_servers = servers;
        self
    }

    /// P5-11 (bounded-context requirement) — see [`Config::lsp_max_diagnostics`].
    pub fn lsp_max_diagnostics(mut self, n: usize) -> Self {
        self.config.lsp_max_diagnostics = n;
        self
    }

    /// P5-11 (bounded-latency requirement) — see [`Config::lsp_timeout_secs`].
    pub fn lsp_timeout_secs(mut self, secs: u64) -> Self {
        self.config.lsp_timeout_secs = secs;
        self
    }

    /// P5-11 (§3.1 `capabilities.formatters.enabled`) — see
    /// [`Config::formatters_enabled`].
    pub fn formatters_enabled(mut self, enabled: bool) -> Self {
        self.config.formatters_enabled = enabled;
        self
    }

    /// P5-11 (`capabilities.formatters.<name>`) — see [`Config::formatters`].
    pub fn formatters(
        mut self,
        formatters: Vec<(String, crate::formatters::FormatterSpec)>,
    ) -> Self {
        self.config.formatters = formatters;
        self
    }

    /// P5-11 (§3.1 `capabilities.formatters.diff_back`, C10) — see
    /// [`Config::formatters_diff_back`].
    pub fn formatters_diff_back(mut self, diff_back: bool) -> Self {
        self.config.formatters_diff_back = diff_back;
        self
    }

    /// P5-11 (bounded-latency requirement) — see [`Config::formatters_timeout_secs`].
    pub fn formatters_timeout_secs(mut self, secs: u64) -> Self {
        self.config.formatters_timeout_secs = secs;
        self
    }

    /// P5-12 (§3.1 `capabilities.trust.enabled`) — see [`Config::trust_enabled`].
    pub fn trust_enabled(mut self, enabled: bool) -> Self {
        self.config.trust_enabled = enabled;
        self
    }

    /// P5-12 (`capabilities.trust.default`) — see [`Config::trust_default`].
    pub fn trust_default(mut self, default: crate::plugins::TrustDecision) -> Self {
        self.config.trust_default = default;
        self
    }

    /// P5-12 (§3.1 `capabilities.plugins.enabled`) — see [`Config::plugins_enabled`].
    pub fn plugins_enabled(mut self, enabled: bool) -> Self {
        self.config.plugins_enabled = enabled;
        self
    }

    /// P5-12 (`capabilities.plugins.dirs`) — see [`Config::plugins_dirs`].
    pub fn plugins_dirs(mut self, dirs: Vec<PathBuf>) -> Self {
        self.config.plugins_dirs = dirs;
        self
    }

    /// Finalize the configuration.
    pub fn build(self) -> Config {
        self.config
    }
}