settings.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/settings.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/unit/test_settings.py"
"""
Central OC_Chat settings — the single source of truth for tunable behaviour.
 
Purpose
-------
Loads ``.oc_chat/oc_chat-settings.json`` (committed project defaults) deep-merged
over the built-in defaults, then deep-merged with an optional gitignored
``oc_chat-settings.local.json`` (per-machine overrides) — the same split as
``.claude/settings.json`` + ``settings.local.json``. Settings migrate here
opportunistically; new settings live here, not as scattered constants.
 
The headline consumers (plan 133): the system-prompt composition (which named
*mode* is active, and which of persona / tools / project-tree / extra files it
injects) and the project-tree generator (exclude dirs/suffixes, honor-gitignore,
work dir).
 
Responsibilities
----------------
- :data:`DEFAULT_SETTINGS` — the built-in schema + safe defaults (mode
  ``standard`` = persona + tools, no tree, no files).
- :class:`OCChatSettings` — the resolved, validated settings + any load-time
  warnings + helpers (:meth:`mode_profile`, :meth:`resolve_mode`).
- :func:`load_settings` — read + deep-merge + validate; never raises on a
  missing/malformed file (falls back to defaults with a warning).
 
Forward compatibility (lenient reader, strict writer)
-----------------------------------------------------
Unknown top-level keys, unknown keys inside a mode profile, and unknown
``project_tree`` keys are recorded as a warning and otherwise ignored, so a
newer settings file (new mode / new toggle) never breaks an older OC_Chat. An
active ``mode`` absent from ``modes`` warns and falls back to ``standard``.
Warnings are returned on :attr:`OCChatSettings.warnings`; the caller surfaces
them (terminal-visible) once a presenter exists.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events (load entry/exit)
    L3 - semantic details (merge sources, fallbacks)
    L4 - deep tracing (per-key unknown-warning emission)
 
Contracts
---------
- :func:`load_settings` is total: any IO/JSON error degrades to defaults + a
  warning; it never raises.
- :class:`OCChatSettings` is read-only by convention after load.
- Deep-merge order is defaults < committed < local; ``modes`` and
  ``project_tree`` merge per-key (a partial override does not drop sibling keys).
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.defaults (shipped built-in values that the settings files merge over)
- oc_chat.core._paths (lazy; find_workspace_root fallback for the settings file location)
- oc_chat.tools.filesystem (lazy; read_prompt_file for the hardened system_prompt_file read)
"""
from __future__ import annotations
 
import json
from copy import deepcopy
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
 
from oc_diagnostics import _dbg
 
# CONFIG-01 (plan 238): the built-in values below are bound at import from the
# shipped, read-only ``oc_chat.defaults.toml``. ``shipped()`` is used rather than
# ``default()`` on purpose — these ARE the built-in defaults a settings file
# merges over, so consulting the settings file to build them would be circular.
from oc_chat.core.defaults import shipped
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
 
#: Committed project settings (relative to the workspace root).
SETTINGS_FILENAME = ".oc_chat/oc_chat-settings.json"
#: Gitignored per-machine override, deep-merged over the committed file.
LOCAL_SETTINGS_FILENAME = ".oc_chat/oc_chat-settings.local.json"
 
 
#: Built-in defaults + the authoritative schema. Anything not here is "unknown".
DEFAULT_SETTINGS: dict[str, Any] = {
    "mode": "standard",
    "modes": {
        "standard": {
            "include_persona": shipped("mode_standard_include_persona"),
            "include_tools": shipped("mode_standard_include_tools"),
            "tools": None,
            "include_env": shipped("mode_standard_include_env"),
            "env_fields": ["date", "timezone"],
            "include_project_tree": shipped("mode_standard_include_project_tree"),
            "include_files": [],
        },
        "option-c": {
            "include_persona": shipped("mode_option_c_include_persona"),
            "include_tools": shipped("mode_option_c_include_tools"),
            "tools": None,
            "include_env": shipped("mode_option_c_include_env"),
            "env_fields": ["date", "timezone", "cwd", "branch", "git", "model", "mode"],
            "include_project_tree": shipped("mode_option_c_include_project_tree"),
            "include_files": ["AGENT_CONTEXT.md"],
        },
    },
    # "" → use the built-in CANONICAL_POLICY; non-empty → inline override.
    "system_prompt": "",
    # None → unused; else a workspace-relative path read as the system prompt.
    "system_prompt_file": None,
    # Plan 134 C1: default launch verbosity. Dev checkouts set true in the
    # gitignored .local.json; shipped quiet for end users. The --verbose /
    # --no-verbose CLI flags override per launch (CLI > local > committed > here).
    "verbose": shipped("settings_verbose"),
    # M8.1 Appendix-B amendment: per-turn tool-call ceiling (was 10).
    # Operator-configurable — raise for large multi-tool turns. Still
    # non-overridable by model args (a runaway model cannot self-raise it) and
    # still clamped by the shipped ceiling — see defaults.ceiling.
    "max_tool_calls_per_turn": shipped("tool_calls_per_turn"),
    # CAPS-02 (plan 246): None is an explicit absent request. This lets an
    # operator's OOB environment ceiling apply when the workspace did not lower it.
    "stall_repeat_calls": None,
    "stall_error_streak": None,
    "stall_no_progress_iterations": None,
    # Per-completion output ceiling. 0 = use the shipped default
    # (config.OUTPUT_TOKENS_CEILING). May only LOWER that default — see
    # config.get_output_tokens_ceiling.
    "max_output_tokens": shipped("settings_max_output_tokens"),
    # CAPS-01 (plan 237): the session dollar hard cap, LOWER-ONLY. 0 = no
    # request, i.e. use the shipped ceiling (or the operator's out-of-band
    # OC_CHAT_SESSION_COST_CEILING_USD). A value above the ceiling is clamped,
    # never honoured — see resource_caps.resolve_session_cost_hard_cap_usd.
    "session_cost_hard_cap_usd": shipped("settings_session_cost_hard_cap_usd"),
    # CAPS-01 (plan 237): EXTRA cost checkpoints, in USD. Merged with the
    # shipped ladder, never replacing it: entries below the shipped ceiling are
    # added (the session asks sooner), entries at or above it are ignored, and
    # no shipped checkpoint can be removed — see resolve_cost_thresholds_usd.
    "session_cost_thresholds_usd": [],
    "project_tree": {
        "max_depth": shipped("project_tree_max_depth"),
        "exclude_dirs": [
            "__pycache__", "logs", "memory_store", "_backup", "nulldir",
            "venv", ".venv",
        ],
        "exclude_suffixes": [".bk", ".bak", "~"],
        # Dirs shown as existence-only (contents omitted, "use list_dir" hint) —
        # high-churn dirs whose individual filenames bloat the prompt for no gain.
        "stub_dirs": ["sessions", "plans"],
        "honor_gitignore": shipped("project_tree_honor_gitignore"),
        "work_dir": "_work",
    },
    # Plan 137: verification backpressure — the inner-loop post-mutation feedback
    # sensor. Off by default globally; an agentic mode opts in via a per-mode
    # ``verification`` override (a known mode key — see ``_MODE_DEFAULTS``).
    # ``subloop_readonly``/``baseline_scope`` use ``None`` sentinels resolved by
    # ``verification_config`` (None subloop_readonly ⇒ follow ``enabled``).
    "verification": {
        "enabled": shipped("verification_enabled"),
        "mutating_tools": ["write_file", "oct_new"],
        "lint": shipped("verification_lint"),
        "typecheck": shipped("verification_typecheck"),
        "tests": shipped("verification_tests"),
        "profile": "default",
        "timeout_s": shipped("verification_timeout_s"),
        "max_files": shipped("verification_max_files"),
        "max_findings": shipped("verification_max_findings"),
        "jobs": shipped("verification_jobs"),
        "max_runs_per_turn": shipped("verification_max_runs_per_turn"),
        "baseline": shipped("verification_baseline"),
        "baseline_timeout_s": shipped("verification_baseline_timeout_s"),
        "baseline_scope": None,
        "subloop_readonly": None,
    },
}
 
#: Neutral per-mode backfill defaults (plan 135 §3.2 table). A partially-declared
#: mode answers every toggle from this dict — NOT from the ``standard`` mode, so
#: ``standard`` is not privileged as a backfill source. For the four pre-135 keys
#: these values equal ``standard``'s, so existing behaviour is unchanged; the new
#: keys (``tools``/``include_env``/``env_fields``) default to the minimal/off form.
_MODE_DEFAULTS: dict[str, Any] = {
    "include_persona": True,
    "include_tools": True,
    "tools": None,
    "include_env": False,
    "env_fields": [],
    "include_project_tree": False,
    "include_files": [],
    # Plan 137: per-mode ``verification`` override is a KNOWN mode key (so it does
    # not warn as unknown). Empty ⇒ the mode inherits the top-level default;
    # ``verification_config`` deep-merges this partial over the top-level block.
    "verification": {},
}
 
 
# Known-key sets resolve from the live dicts at CALL time (not module-import
# time) so a test that patches DEFAULT_SETTINGS / _MODE_DEFAULTS sees the
# current schema and new keys never emit spurious forward-compat warnings (§4.2).
def _known_top_keys() -> frozenset[str]:
    return frozenset(DEFAULT_SETTINGS)
 
 
def _known_mode_keys() -> frozenset[str]:
    return frozenset(_MODE_DEFAULTS)
 
 
def _known_tree_keys() -> frozenset[str]:
    return frozenset(DEFAULT_SETTINGS["project_tree"])
 
 
@dataclass
class OCChatSettings:
    """Resolved, validated settings. Read-only by convention after load."""
 
    mode: str
    modes: dict[str, dict[str, Any]]
    system_prompt: str
    system_prompt_file: str | None
    project_tree: dict[str, Any]
    verbose: bool = shipped("settings_verbose")
    # M8.1 Appendix-B (amended): operator-configurable per-turn tool-call ceiling,
    # non-overridable by model args (was 10).
    max_tool_calls_per_turn: int = shipped("tool_calls_per_turn")
    # CAPS-02: lower-only requests. None means the workspace made no request.
    stall_repeat_calls: int | None = None
    stall_error_streak: int | None = None
    stall_no_progress_iterations: int | None = None
    # Lower-only override of config.OUTPUT_TOKENS_CEILING; 0 = shipped default.
    max_output_tokens: int = shipped("settings_max_output_tokens")
    # CAPS-01: lower-only session dollar cap (0 = no request) and EXTRA cost
    # checkpoints (merged below the shipped ceiling, never replacing the ladder).
    session_cost_hard_cap_usd: int = shipped("settings_session_cost_hard_cap_usd")
    session_cost_thresholds_usd: list[float] = field(default_factory=list)
    # Plan 137: resolved top-level ``verification`` block; per-mode overrides live
    # under ``modes[<mode>]["verification"]`` and are composed by ``verification_config``.
    verification: dict[str, Any] = field(default_factory=dict)
    warnings: list[str] = field(default_factory=list)
 
    def resolve_mode(self, cli_mode: str | None) -> str:
        """Pick the effective mode: CLI override > file `mode` > 'standard'.
 
        An unknown name (from either source) warns and falls back to a defined
        mode ('standard' if present, else the first defined mode)."""
        chosen = (cli_mode or self.mode or "standard").strip()
        if chosen in self.modes:
            return chosen
        fallback = "standard" if "standard" in self.modes else next(iter(self.modes), "standard")
        self.warnings.append(
            f"unknown mode {chosen!r} (not in modes: {sorted(self.modes)}); using {fallback!r}"
        )
        return fallback
 
    def mode_profile(self, name: str) -> dict[str, Any]:
        """Composition toggles for *name*, backfilled from the neutral mode
        defaults so a partially-specified mode still answers every toggle.
 
        Backfill source is :data:`_MODE_DEFAULTS` (the §3.2 schema), not the
        ``standard`` mode — so ``standard`` carries no privileged status and a
        new mode that omits a key gets the minimal/off default, not standard's.
        """
        base = deepcopy(_MODE_DEFAULTS)
        base.update(self.modes.get(name, {}))
        return base
 
    def drain_warnings(self) -> list[str]:
        """Return and clear pending warnings (emit-once across call sites)."""
        out = list(self.warnings)
        self.warnings.clear()
        return out
 
 
def _read_json(path: Path, warnings: list[str]) -> dict[str, Any]:
    """Best-effort JSON read; a malformed/unreadable file warns and yields {}."""
    try:
        text = path.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError):
        return {}
    try:
        data = json.loads(text)
    except json.JSONDecodeError as exc:
        warnings.append(f"{path.name}: invalid JSON ({exc}); ignored")
        return {}
    if not isinstance(data, dict):
        warnings.append(f"{path.name}: top-level value must be an object; ignored")
        return {}
    return data
 
 
def _deep_merge(base: dict[str, Any], over: dict[str, Any]) -> dict[str, Any]:
    """Recursively merge *over* onto *base* (dicts merge per-key; others replace)."""
    out = deepcopy(base)
    for k, v in over.items():
        if isinstance(v, dict) and isinstance(out.get(k), dict):
            out[k] = _deep_merge(out[k], v)
        else:
            out[k] = deepcopy(v)
    return out
 
 
def _as_int(raw: Any, fallback: int) -> int:
    """Coerce a settings value to ``int``, degrading to *fallback* (plan 237).
 
    ``load_settings`` is total by contract, so a hostile or fat-fingered value
    must not raise. Both CAPS-01 keys are lower-only requests, and the fallback
    for both is "no request" — the bounded shipped value, never "unbounded"."""
    try:
        return int(raw)  # type: ignore[arg-type]
    except (TypeError, ValueError):
        return fallback
 
 
def _as_positive_int_or_none(
    raw: Any, *, key: str, warnings: list[str],
) -> int | None:
    """Read a positive integer request; tolerate invalid values as absent."""
    if raw is None:
        return None
    try:
        value = int(raw)
    except (TypeError, ValueError):
        value = 0
    if isinstance(raw, bool) or value <= 0:
        warnings.append(
            f"setting {key!r} must be a positive integer; ignoring {raw!r}"
        )
        return None
    return value
 
 
def _as_float_list(raw: Any) -> list[float]:
    """Coerce a settings value to a list of floats, dropping what will not parse."""
    if not isinstance(raw, (list, tuple)):
        return []
    out: list[float] = []
    for item in raw:
        try:
            out.append(float(item))
        except (TypeError, ValueError):
            continue
    return out
 
 
def _warn_unknown(raw: dict[str, Any], warnings: list[str]) -> None:
    """Record (but tolerate) keys not in the known schema — forward-compat."""
    known_top = _known_top_keys()
    known_mode = _known_mode_keys()
    known_tree = _known_tree_keys()
    for k in raw:
        if k not in known_top:
            warnings.append(f"unknown setting {k!r} ignored (forward-compat)")
    for mode_name, profile in (raw.get("modes") or {}).items():
        if isinstance(profile, dict):
            for k in profile:
                if k not in known_mode:
                    warnings.append(
                        f"unknown key {k!r} in mode {mode_name!r} ignored (forward-compat)"
                    )
    tree = raw.get("project_tree")
    if isinstance(tree, dict):
        for k in tree:
            if k not in known_tree:
                warnings.append(
                    f"unknown project_tree key {k!r} ignored (forward-compat)"
                )
 
 
def load_settings(workspace_root: Path | str | None = None) -> OCChatSettings:
    """Load + deep-merge + validate settings. Never raises (degrades to defaults).
 
    Merge order: built-in defaults < committed ``oc_chat-settings.json`` <
    gitignored ``oc_chat-settings.local.json``. Unknown keys in the user files
    are warned and ignored (forward-compat); the merged result still validates
    against the known schema."""
    func = "load_settings"
    warnings: list[str] = []
 
    if workspace_root is None:
        # Plan 151 T2 step 11(b) — BOUNDED subproject-root resolution (the
        # session_log V23 pattern: one adjacency check, no upward walk).
        # Post-monorepo-migration find_workspace_root() returns the OUTERMOST
        # .git (the option_c monorepo root), while the committed settings live
        # at the oc_chat SUBPROJECT root — the zero-arg form silently degraded
        # to defaults. The subproject root is the parent of the oc_chat package
        # dir; if the committed settings file sits there, use it. Otherwise
        # (wheel install / unusual layout) fall back to the old resolver.
        pkg_parent = Path(__file__).resolve().parent.parent.parent
        if (pkg_parent / SETTINGS_FILENAME).is_file():
            root = pkg_parent
        else:
            try:
                from oc_chat.core._paths import find_workspace_root
                root = find_workspace_root()
            except (FileNotFoundError, Exception):  # noqa: BLE001 - total by contract
                root = Path.cwd()
    else:
        root = Path(workspace_root)
 
    committed = _read_json(root / SETTINGS_FILENAME, warnings)
    local = _read_json(root / LOCAL_SETTINGS_FILENAME, warnings)
 
    # Warn on unknown keys in BOTH user files (before they're dropped by merge).
    _warn_unknown(committed, warnings)
    _warn_unknown(local, warnings)
 
    merged = _deep_merge(DEFAULT_SETTINGS, committed)
    merged = _deep_merge(merged, local)
 
    settings = OCChatSettings(
        mode=str(merged.get("mode") or "standard"),
        modes={k: dict(v) for k, v in (merged.get("modes") or {}).items() if isinstance(v, dict)},
        system_prompt=str(merged.get("system_prompt") or ""),
        system_prompt_file=(merged.get("system_prompt_file") or None),
        project_tree=dict(merged.get("project_tree") or {}),
        verbose=bool(merged.get("verbose", shipped("settings_verbose"))),
        max_tool_calls_per_turn=int(
            merged.get("max_tool_calls_per_turn", shipped("tool_calls_per_turn"))),
        stall_repeat_calls=_as_positive_int_or_none(
            merged.get("stall_repeat_calls"),
            key="stall_repeat_calls",
            warnings=warnings,
        ),
        stall_error_streak=_as_positive_int_or_none(
            merged.get("stall_error_streak"),
            key="stall_error_streak",
            warnings=warnings,
        ),
        stall_no_progress_iterations=_as_positive_int_or_none(
            merged.get("stall_no_progress_iterations"),
            key="stall_no_progress_iterations",
            warnings=warnings,
        ),
        max_output_tokens=int(
            merged.get("max_output_tokens", shipped("settings_max_output_tokens"))),
        # CAPS-01: read tolerantly — a malformed value must degrade to "no
        # request" (the bounded shipped cap / the shipped ladder), never abort
        # the load, because load_settings is total by contract.
        session_cost_hard_cap_usd=_as_int(
            merged.get("session_cost_hard_cap_usd"),
            shipped("settings_session_cost_hard_cap_usd")),
        session_cost_thresholds_usd=_as_float_list(
            merged.get("session_cost_thresholds_usd")),
        verification=deepcopy(merged.get("verification") or {}),
        warnings=warnings,
    )
    _dbg("OC_CHAT.MAIN", func,
         f"loaded mode={settings.mode} modes={sorted(settings.modes)} "
         f"committed={bool(committed)} local={bool(local)} warnings={len(warnings)}", 2)
    return settings
 
 
def resolve_system_prompt(
    settings: OCChatSettings, *, default: str, workspace_root: Path | str | None = None,
) -> str:
    """Pick the persona text: non-empty inline `system_prompt` > readable
    `system_prompt_file` > built-in *default*. If both inline and file are set,
    warn and use inline. A set-but-unreadable file warns and falls back."""
    if settings.system_prompt.strip():
        if settings.system_prompt_file:
            settings.warnings.append(
                "both system_prompt and system_prompt_file set; using inline system_prompt"
            )
        return settings.system_prompt
    spf = settings.system_prompt_file
    if spf:
        # M8.0 WU-2b (F73): route system_prompt_file through the hardened
        # prompt-read primitive -- forbid absolute paths, clamp to the effective
        # sandbox root, deny the protected-read (secret) class -- so a secret
        # cannot be injected into messages[0] and egressed to the provider. The
        # effective sandbox root (WU-1) supersedes the legacy workspace_root for
        # this clamp; the parameter is retained for signature compatibility.
        try:
            from oc_chat.tools.filesystem import read_prompt_file
            return read_prompt_file(spf)
        except PermissionError as exc:
            settings.warnings.append(
                f"system_prompt_file {spf!r} refused ({exc}); using built-in default"
            )
        except (OSError, UnicodeDecodeError):
            settings.warnings.append(
                f"system_prompt_file {spf!r} empty or unreadable; using built-in default"
            )
    return default
 
 
# ── Process-level runtime mode (the launch setting) ───────────────────────
# The active mode is a per-process launch choice (settings default + CLI
# override), resolved once and read by the prompt-composition functions.
_RUNTIME: OCChatSettings | None = None
_RUNTIME_MODE: str = "standard"
 
 
def init_runtime_settings(
    cli_mode: str | None = None, *, workspace_root: Path | str | None = None,
) -> OCChatSettings:
    """Resolve + cache the process settings and effective mode. Call once at
    launch (after CLI parse). ``cli_mode`` overrides the file's ``mode``."""
    func = "init_runtime_settings"
    global _RUNTIME, _RUNTIME_MODE
    _RUNTIME = load_settings(workspace_root)
    _RUNTIME_MODE = _RUNTIME.resolve_mode(cli_mode)
    _dbg("OC_CHAT.MAIN", func, f"effective mode={_RUNTIME_MODE}", 2)
    return _RUNTIME
 
 
def runtime_settings() -> OCChatSettings:
    """The cached process settings (lazily loaded with defaults if uninitialised)."""
    if _RUNTIME is None:
        init_runtime_settings()
    assert _RUNTIME is not None
    return _RUNTIME
 
 
def runtime_mode() -> str:
    """The effective active mode for this process."""
    if _RUNTIME is None:
        init_runtime_settings()
    return _RUNTIME_MODE
 
 
def active_profile() -> dict[str, Any]:
    """Composition toggles for the effective mode (backfilled defaults)."""
    return runtime_settings().mode_profile(runtime_mode())
 
 
def resolve_tool_filter(profile: dict[str, Any]) -> list[str] | None:
    """Per-mode tool whitelist with IDENTITY semantics (plan 135 §3.2).
 
    The single helper used at every tool-consumption point (registry, API
    schemas, compact map). Returns:
      * ``[]`` when the mode exposes no tools (``include_tools`` false, or
        ``tools == []``) — an explicit empty whitelist;
      * ``None`` when the mode exposes ALL discovered tools (``tools`` absent or
        explicitly ``null``);
      * the explicit list otherwise (a subset).
 
    Never branch on ``if profile.get("tools")`` — that conflates ``[]`` (none)
    with ``None`` (all). This function keys on ``is None``.
    """
    if not profile.get("include_tools", True):
        return []
    tools = profile.get("tools")
    if tools is None:
        return None
    return list(tools)
 
 
def reset_runtime_settings_for_tests() -> None:
    """Test helper: clear the cached runtime settings so the next access reloads."""
    global _RUNTIME, _RUNTIME_MODE
    _RUNTIME = None
    _RUNTIME_MODE = "standard"
 
 
# ── Plan 137: verification-backpressure config (typed resolver) ───────────────
 
 
@dataclass
class VerificationConfig:
    """Resolved, typed verification-backpressure config (plan 137 §3.7).
 
    Built by :func:`verification_config` from the deep-merge of the top-level
    ``verification`` block with the active mode's partial override. ``react_loop``
    and the sensor consume this typed shape, never ad-hoc nested dicts.
    """
 
    enabled: bool = shipped("verification_enabled")
    mutating_tools: tuple[str, ...] = ("write_file", "oct_new")
    lint: bool = shipped("verification_lint")
    typecheck: bool = shipped("verification_typecheck")
    tests: bool = shipped("verification_tests")
    profile: str = "default"
    timeout_s: int = shipped("verification_timeout_s")
    max_files: int = shipped("verification_max_files")
    max_findings: int = shipped("verification_max_findings")
    jobs: int = shipped("verification_jobs")
    max_runs_per_turn: int = shipped("verification_max_runs_per_turn")
    baseline: bool = shipped("verification_baseline")
    baseline_timeout_s: int = shipped("verification_baseline_timeout_s")
    baseline_scope: tuple[str, ...] | None = None
    # Not a DEFAULT_SETTINGS leaf: the settings schema carries ``None`` here and
    # ``verification_config`` resolves None to follow ``enabled``. This dataclass
    # default is the resolved off-state, deliberately NOT coupled to the shipped
    # ``verification_enabled`` value.
    subloop_readonly: bool = False
 
 
def verification_config(settings: OCChatSettings, mode: str | None = None) -> VerificationConfig:
    """Resolve the typed :class:`VerificationConfig` for *mode* (plan 137 §3.7).
 
    Precedence: built-in defaults < committed/local top-level ``verification``
    (already folded into ``settings.verification`` by :func:`load_settings`) <
    the active mode's per-mode ``verification`` override. The override is
    **deep-merged** over the top-level block (``mode_profile``'s shallow update is
    not relied upon for the sub-keys). ``subloop_readonly`` defaults to follow
    ``enabled`` when unset (``None``), so the off path is byte-identical.
    """
    func = "verification_config"
    top: dict[str, Any] = dict(settings.verification or {})
    override: dict[str, Any] = {}
    if mode:
        ov = (settings.modes.get(mode) or {}).get("verification")
        if isinstance(ov, dict):
            override = ov
    merged = _deep_merge(top, override) if override else top
 
    enabled = bool(merged.get("enabled", shipped("verification_enabled")))
    raw_subloop = merged.get("subloop_readonly", None)
    subloop_readonly = enabled if raw_subloop is None else bool(raw_subloop)
 
    raw_scope = merged.get("baseline_scope", None)
    if raw_scope is None:
        scope: tuple[str, ...] | None = None
    elif isinstance(raw_scope, (list, tuple)):
        scope = tuple(str(s) for s in raw_scope)
    else:
        scope = (str(raw_scope),)
 
    cfg = VerificationConfig(
        enabled=enabled,
        mutating_tools=tuple(merged.get("mutating_tools") or ("write_file", "oct_new")),
        lint=bool(merged.get("lint", shipped("verification_lint"))),
        typecheck=bool(merged.get("typecheck", shipped("verification_typecheck"))),
        tests=bool(merged.get("tests", shipped("verification_tests"))),
        profile=str(merged.get("profile") or "default"),
        timeout_s=int(merged.get("timeout_s", shipped("verification_timeout_s"))),
        max_files=int(merged.get("max_files", shipped("verification_max_files"))),
        max_findings=int(merged.get("max_findings", shipped("verification_max_findings"))),
        jobs=int(merged.get("jobs", shipped("verification_jobs"))),
        max_runs_per_turn=int(
            merged.get("max_runs_per_turn", shipped("verification_max_runs_per_turn"))),
        baseline=bool(merged.get("baseline", shipped("verification_baseline"))),
        baseline_timeout_s=int(
            merged.get("baseline_timeout_s", shipped("verification_baseline_timeout_s"))),
        baseline_scope=scope,
        subloop_readonly=subloop_readonly,
    )
    _dbg("OC_CHAT.MAIN", func,
         f"mode={mode} enabled={cfg.enabled} subloop_readonly={cfg.subloop_readonly}", 3)
    return cfg