py-opencode-wrapper 0.1.5__tar.gz → 0.2.1__tar.gz

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-opencode-wrapper
-Version: 0.1.5
+Version: 0.2.1
 Summary: Async Python wrapper for OpenCode CLI (opencode run --format json)
 Project-URL: Homepage, https://github.com/idailylife/oc_py_wrapper
 Project-URL: Repository, https://github.com/idailylife/oc_py_wrapper
@@ -104,11 +104,29 @@ Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode c
 | `permission` | `permission` map (`allow` / `deny`, patterns) |
 | `mcp` | MCP server definitions |
 | `tools` | Enable/disable tools (including MCP globs) |
+| `instructions` | Instruction file paths / glob patterns to inject |
 | `config_overrides` | Any extra top-level config keys to deep-merge |
 
 Optional env tuning: `disable_autoupdate=True` sets `OPENCODE_DISABLE_AUTOUPDATE=1`.
 Note: `ask` is intentionally rejected in subprocess mode (no interactive terminal); use `allow` or `deny`.
 
+### User config isolation
+
+By default, `RunConfig.inherit_user_config=False` makes each child `opencode`
+process see a sanitized copy of the host's global OpenCode config. The wrapper
+keeps only provider-selection keys (`$schema`, `provider`,
+`disabled_providers`, `enabled_providers`) and drops capability/configuration
+keys such as `mcp`, `agent`, `command`, `tools`, `plugin`, `skills`,
+`instructions`, `permission`, and `model`.
+
+This keeps benchmark and orchestration runs reproducible while still allowing
+provider configuration and `opencode auth` credentials to work. Project-level
+config discovered from the workspace is not suppressed.
+
+Set `inherit_user_config=True` to restore the legacy behavior of inheriting the
+host OpenCode config as-is. For reproducible runs, pass `model`, `permission`,
+`mcp`, `tools`, and `instructions` explicitly through `RunConfig`.
+
 ## CLI arguments
 
 `RunConfig` maps to flags such as `--agent`, `-m`, `-f`, `--attach`, `--title`, etc. Prompt text is appended as the final `opencode run` message argument.

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/README.md

@@ -91,11 +91,29 @@ Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode c
 | `permission` | `permission` map (`allow` / `deny`, patterns) |
 | `mcp` | MCP server definitions |
 | `tools` | Enable/disable tools (including MCP globs) |
+| `instructions` | Instruction file paths / glob patterns to inject |
 | `config_overrides` | Any extra top-level config keys to deep-merge |
 
 Optional env tuning: `disable_autoupdate=True` sets `OPENCODE_DISABLE_AUTOUPDATE=1`.
 Note: `ask` is intentionally rejected in subprocess mode (no interactive terminal); use `allow` or `deny`.
 
+### User config isolation
+
+By default, `RunConfig.inherit_user_config=False` makes each child `opencode`
+process see a sanitized copy of the host's global OpenCode config. The wrapper
+keeps only provider-selection keys (`$schema`, `provider`,
+`disabled_providers`, `enabled_providers`) and drops capability/configuration
+keys such as `mcp`, `agent`, `command`, `tools`, `plugin`, `skills`,
+`instructions`, `permission`, and `model`.
+
+This keeps benchmark and orchestration runs reproducible while still allowing
+provider configuration and `opencode auth` credentials to work. Project-level
+config discovered from the workspace is not suppressed.
+
+Set `inherit_user_config=True` to restore the legacy behavior of inheriting the
+host OpenCode config as-is. For reproducible runs, pass `model`, `permission`,
+`mcp`, `tools`, and `instructions` explicitly through `RunConfig`.
+
 ## CLI arguments
 
 `RunConfig` maps to flags such as `--agent`, `-m`, `-f`, `--attach`, `--title`, etc. Prompt text is appended as the final `opencode run` message argument.

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/opencode_wrapper/client.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import os
 import shutil
 import tempfile
@@ -12,6 +13,7 @@ from pathlib import Path
 from typing import Any, AsyncIterator, Mapping
 
 from opencode_wrapper.config import RunConfig, validate_config_for_run
+from opencode_wrapper.config import loads_jsonc, sanitize_user_config_json
 from opencode_wrapper.errors import (
     OpenCodeBinaryNotFoundError,
     OpenCodeProcessError,
@@ -79,7 +81,12 @@ def build_argv(
     return cmd
 
 
-def build_env(run_cfg: RunConfig, base: Mapping[str, str] | None = None) -> dict[str, str]:
+def build_env(
+    run_cfg: RunConfig,
+    base: Mapping[str, str] | None = None,
+    *,
+    cwd: str | Path | None = None,
+) -> dict[str, str]:
     env = dict(base if base is not None else os.environ)
     if run_cfg.extra_env:
         env.update(dict(run_cfg.extra_env))
@@ -88,6 +95,14 @@ def build_env(run_cfg: RunConfig, base: Mapping[str, str] | None = None) -> dict
         env["OPENCODE_CONFIG_CONTENT"] = content
     if run_cfg.disable_autoupdate:
         env["OPENCODE_DISABLE_AUTOUPDATE"] = "1"
+    # opencode's `run` cmd resolves the project root as
+    # `process.env.PWD ?? process.cwd()` (run.ts:276), and the bash builtin
+    # `pwd` reads $PWD too.  asyncio.create_subprocess_exec(cwd=...) only
+    # chdirs the child; it leaves PWD inherited from the parent shell, which
+    # makes opencode operate against the wrong directory.  Pin PWD to the
+    # resolved workspace so the child sees a consistent cwd.
+    if cwd is not None:
+        env["PWD"] = str(cwd)
     return env
 
 
@@ -158,6 +173,96 @@ def _is_sqlite_startup_error(stderr: str) -> bool:
     return any(pat in lower for pat in _SQLITE_STARTUP_PATTERNS)
 
 
+_LOG = logging.getLogger(__name__)
+
+# Filenames opencode reads from its global config dir + ~/.opencode.
+# Legacy TOML ("config" without extension) is intentionally skipped — it's rare
+# and would require a TOML parser dep; the wrapper aims for stdlib-only.
+_GLOBAL_CONFIG_FILENAMES: tuple[str, ...] = (
+    "config.json",
+    "opencode.json",
+    "opencode.jsonc",
+)
+
+
+def _resolve_real_xdg_config_opencode_dir(env: Mapping[str, str]) -> Path:
+    xdg = env.get("XDG_CONFIG_HOME")
+    base = Path(xdg).expanduser() if xdg else Path(env.get("HOME", str(Path.home()))).expanduser() / ".config"
+    return base / "opencode"
+
+
+def _resolve_real_home_opencode_dir(env: Mapping[str, str]) -> Path:
+    return Path(env.get("HOME", str(Path.home()))).expanduser() / ".opencode"
+
+
+def _sanitize_and_copy(src_dir: Path, dst_dir: Path) -> None:
+    """Read each known opencode config file in *src_dir*, sanitize, write to *dst_dir*.
+
+    Strict JSON files parse on the fast path; JSONC (comments, trailing commas)
+    falls back to ``loads_jsonc``.  Files that aren't valid in either form are
+    skipped with a warning — for benchmark reproducibility the wrapper would
+    rather hide a file it can't safely strip than risk leaking capability keys.
+    Missing source files are silently skipped.  ``dst_dir`` is always created
+    so opencode finds the directory (even if empty).
+    """
+    from opencode_wrapper.config import sanitize_user_config_json
+
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    if not src_dir.is_dir():
+        return
+    for fname in _GLOBAL_CONFIG_FILENAMES:
+        src = src_dir / fname
+        if not src.is_file():
+            continue
+        try:
+            text = src.read_text(encoding="utf-8")
+        except OSError as exc:
+            _LOG.warning("user-config isolation: cannot read %s: %s", src, exc)
+            continue
+        try:
+            raw = loads_jsonc(text)
+        except json.JSONDecodeError as exc:
+            _LOG.warning(
+                "user-config isolation: skipping %s (not parseable as JSON or JSONC): %s",
+                src, exc,
+            )
+            continue
+        if not isinstance(raw, dict):
+            _LOG.warning(
+                "user-config isolation: skipping %s (root is not a JSON object)", src
+            )
+            continue
+        sanitized = sanitize_user_config_json(raw)
+        (dst_dir / fname).write_text(
+            json.dumps(sanitized, ensure_ascii=False), encoding="utf-8"
+        )
+
+
+def _isolate_user_config(env: dict[str, str], tmp_root: Path) -> dict[str, str]:
+    """Mutate *env* so opencode sees a sanitized copy of the user's global config.
+
+    Reads the real ``$XDG_CONFIG_HOME/opencode`` and ``$HOME/.opencode``,
+    filters each file through ``sanitize_user_config_json`` (keeping only
+    ``provider`` / ``disabled_providers`` / ``enabled_providers`` / ``$schema``),
+    writes the results under *tmp_root*, and points ``XDG_CONFIG_HOME`` /
+    ``OPENCODE_TEST_HOME`` at those tmpdir locations.  Strips
+    ``OPENCODE_CONFIG`` / ``OPENCODE_CONFIG_DIR`` so the parent shell can't
+    re-introduce extras.  Project-level config (cwd walk + ``.opencode/``)
+    is untouched.
+    """
+    iso_xdg = tmp_root / "xdg"
+    iso_home = tmp_root / "home"
+
+    _sanitize_and_copy(_resolve_real_xdg_config_opencode_dir(env), iso_xdg / "opencode")
+    _sanitize_and_copy(_resolve_real_home_opencode_dir(env), iso_home / ".opencode")
+
+    env["XDG_CONFIG_HOME"] = str(iso_xdg)
+    env["OPENCODE_TEST_HOME"] = str(iso_home)
+    env.pop("OPENCODE_CONFIG", None)
+    env.pop("OPENCODE_CONFIG_DIR", None)
+    return env
+
+
 class AsyncOpenCodeClient:
     """
     One-shot async wrapper around the OpenCode CLI.
@@ -207,13 +312,16 @@ class AsyncOpenCodeClient:
         argv: list[str],
         cwd: str,
         env: dict[str, str],
+        run_cfg: RunConfig,
     ) -> AsyncIterator[tuple[asyncio.subprocess.Process, list[str]]]:
         stderr_lines: list[str] = []
+        cleanup_tmpdirs: list[str] = []
         # Give each process its own XDG_DATA_HOME so opencode.db is isolated.
         # Without this, all concurrent processes share ~/.local/share/opencode/opencode.db
         # and SQLite write locks during tool execution serialize the runs (37–46s delays).
         if self._isolate_db:
             xdg_tmpdir = tempfile.mkdtemp(prefix="oc_xdg_")
+            cleanup_tmpdirs.append(xdg_tmpdir)
             # Symlink auth.json so provider API keys (stored by `opencode auth`)
             # are visible in the isolated data dir.  Without this, providers
             # that rely on auth.json (rather than env-var keys) fail with
@@ -225,8 +333,16 @@ class AsyncOpenCodeClient:
                 iso_oc_dir.mkdir(parents=True, exist_ok=True)
                 (iso_oc_dir / "auth.json").symlink_to(real_auth)
             env = {**env, "XDG_DATA_HOME": xdg_tmpdir}
-        else:
-            xdg_tmpdir = None
+        # When the caller has not opted into host-config inheritance (the
+        # default), redirect XDG_CONFIG_HOME / OPENCODE_TEST_HOME at a sanitized
+        # tmpdir copy of the user's global config — only provider settings are
+        # carried over, all capability keys (mcp / agent / command / tools /
+        # plugin / skills / instructions / permission / model / ...) are stripped.
+        # Project-level config (cwd walk + .opencode/) is untouched.
+        if not run_cfg.inherit_user_config:
+            cfg_tmpdir = tempfile.mkdtemp(prefix="oc_cfg_")
+            cleanup_tmpdirs.append(cfg_tmpdir)
+            env = _isolate_user_config(dict(env), Path(cfg_tmpdir))
         # Serialise process startup to avoid the SQLite WAL-pragma race.
         # The semaphore is released as soon as the startup window has elapsed,
         # so all processes run concurrently after their individual delay.
@@ -257,8 +373,8 @@ class AsyncOpenCodeClient:
                 await stderr_task
             except asyncio.CancelledError:
                 pass
-            if xdg_tmpdir is not None:
-                shutil.rmtree(xdg_tmpdir, ignore_errors=True)
+            for path in cleanup_tmpdirs:
+                shutil.rmtree(path, ignore_errors=True)
 
     async def async_stream(
         self,
@@ -277,13 +393,13 @@ class AsyncOpenCodeClient:
         validate_config_for_run(run_cfg)
         bin_path = self.resolved_binary()
         argv = build_argv(bin_path, prompt, run_cfg)
-        env = build_env(run_cfg)
         cwd = str(Path(workspace).expanduser().resolve())
+        env = build_env(run_cfg, cwd=cwd)
 
         events_acc: list[dict[str, Any]] = []
         raw_acc: list[str] = []
 
-        async with self._managed_process(argv, cwd, env) as (proc, stderr_lines):
+        async with self._managed_process(argv, cwd, env, run_cfg) as (proc, stderr_lines):
             async for line, ev in _stdout_line_event_iter(proc):
                 raw_acc.append(line)
                 events_acc.append(ev)
@@ -333,15 +449,15 @@ class AsyncOpenCodeClient:
             validate_config_for_run(run_cfg)
             bin_path = self.resolved_binary()
             argv = build_argv(bin_path, prompt, run_cfg)
-            env = build_env(run_cfg)
             cwd = str(Path(workspace).expanduser().resolve())
+            env = build_env(run_cfg, cwd=cwd)
 
             events_acc: list[dict[str, Any]] = []
             raw_acc: list[str] = []
 
             log_fh = open(log_file, "w") if log_file is not None else None
             try:
-                async with self._managed_process(argv, cwd, env) as (proc, stderr_lines):
+                async with self._managed_process(argv, cwd, env, run_cfg) as (proc, stderr_lines):
                     async for line, ev in _stdout_line_event_iter(proc):
                         raw_acc.append(line)
                         events_acc.append(ev)

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/opencode_wrapper/config.py

@@ -13,6 +13,107 @@ PermissionAction = str  # "allow" | "ask" | "deny"
 # Nested permission maps: tool name -> action or pattern -> action
 PermissionMap = Dict[str, Any]
 
+# Top-level keys retained from the host's global opencode config when
+# inherit_user_config=False.  Everything else (mcp / agent / command / skills /
+# plugin / tools / instructions / permission / model / ...) is dropped to make
+# benchmark runs reproducible.
+PRESERVE_KEYS: frozenset[str] = frozenset(
+    {
+        "$schema",
+        "provider",
+        "disabled_providers",
+        "enabled_providers",
+    }
+)
+
+
+def sanitize_user_config_json(raw: Mapping[str, Any]) -> dict[str, Any]:
+    """Filter a parsed opencode config dict to the benchmark-safe preserve set.
+
+    Only ``PRESERVE_KEYS`` survive; everything else — including capability keys
+    like ``mcp`` / ``agent`` / ``command`` / ``tools`` / ``plugin`` / ``skills``
+    and the default ``model`` — is removed.  Benchmark callers re-inject the
+    bits they need via ``RunConfig``.
+    """
+    return {k: v for k, v in raw.items() if k in PRESERVE_KEYS}
+
+
+def strip_jsonc(source: str) -> str:
+    """Convert a JSONC source string to strict JSON.
+
+    Supports the JSONC superset accepted by opencode (and VS Code's
+    jsonc-parser): ``//`` line comments, ``/* ... */`` block comments, and
+    trailing commas in objects/arrays.  Strings — including ones that contain
+    ``//`` or ``/*`` — are preserved verbatim, with backslash escape sequences
+    handled.  Unterminated block comments swallow the rest of the input.
+
+    Stdlib-only — keeps the wrapper's zero-runtime-deps invariant.
+    """
+    out: list[str] = []
+    i = 0
+    n = len(source)
+    while i < n:
+        c = source[i]
+        # JSON string: copy verbatim, handle escapes
+        if c == '"':
+            out.append(c)
+            i += 1
+            while i < n:
+                cc = source[i]
+                out.append(cc)
+                if cc == "\\" and i + 1 < n:
+                    out.append(source[i + 1])
+                    i += 2
+                    continue
+                i += 1
+                if cc == '"':
+                    break
+            continue
+        # Line comment: drop through newline (keep newline for line accuracy)
+        if c == "/" and i + 1 < n and source[i + 1] == "/":
+            nl = source.find("\n", i + 2)
+            i = n if nl == -1 else nl
+            continue
+        # Block comment: drop through closing */
+        if c == "/" and i + 1 < n and source[i + 1] == "*":
+            end = source.find("*/", i + 2)
+            i = n if end == -1 else end + 2
+            continue
+        # Possible trailing comma: peek ahead past whitespace/comments
+        if c == ",":
+            j = i + 1
+            while j < n:
+                cj = source[j]
+                if cj.isspace():
+                    j += 1
+                elif cj == "/" and j + 1 < n and source[j + 1] == "/":
+                    nl = source.find("\n", j + 2)
+                    j = n if nl == -1 else nl
+                elif cj == "/" and j + 1 < n and source[j + 1] == "*":
+                    end = source.find("*/", j + 2)
+                    j = n if end == -1 else end + 2
+                else:
+                    break
+            if j < n and source[j] in "}]":
+                i += 1  # drop the trailing comma
+                continue
+        out.append(c)
+        i += 1
+    return "".join(out)
+
+
+def loads_jsonc(source: str) -> Any:
+    """Parse a JSON or JSONC string, falling back to JSONC stripping on failure.
+
+    The fast path is plain ``json.loads`` — most files are strict JSON.
+    On failure we strip JSONC syntax and retry once.  The caller catches
+    ``json.JSONDecodeError`` if even the stripped form is invalid.
+    """
+    try:
+        return json.loads(source)
+    except json.JSONDecodeError:
+        return json.loads(strip_jsonc(source))
+
 
 def _deep_merge(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
     out = dict(base)
@@ -50,6 +151,7 @@ class RunConfig:
     print_logs: bool | None = None
     log_level: str | None = None
     disable_autoupdate: bool = True
+    inherit_user_config: bool = False
     extra_env: Mapping[str, str] | None = None
     # Injected as JSON via OPENCODE_CONFIG_CONTENT (merged with config_overrides)
     permission: PermissionMap | None = None

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/py_opencode_wrapper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-opencode-wrapper
-Version: 0.1.5
+Version: 0.2.1
 Summary: Async Python wrapper for OpenCode CLI (opencode run --format json)
 Project-URL: Homepage, https://github.com/idailylife/oc_py_wrapper
 Project-URL: Repository, https://github.com/idailylife/oc_py_wrapper
@@ -104,11 +104,29 @@ Per-call JSON is merged and passed as `OPENCODE_CONFIG_CONTENT` (see [OpenCode c
 | `permission` | `permission` map (`allow` / `deny`, patterns) |
 | `mcp` | MCP server definitions |
 | `tools` | Enable/disable tools (including MCP globs) |
+| `instructions` | Instruction file paths / glob patterns to inject |
 | `config_overrides` | Any extra top-level config keys to deep-merge |
 
 Optional env tuning: `disable_autoupdate=True` sets `OPENCODE_DISABLE_AUTOUPDATE=1`.
 Note: `ask` is intentionally rejected in subprocess mode (no interactive terminal); use `allow` or `deny`.
 
+### User config isolation
+
+By default, `RunConfig.inherit_user_config=False` makes each child `opencode`
+process see a sanitized copy of the host's global OpenCode config. The wrapper
+keeps only provider-selection keys (`$schema`, `provider`,
+`disabled_providers`, `enabled_providers`) and drops capability/configuration
+keys such as `mcp`, `agent`, `command`, `tools`, `plugin`, `skills`,
+`instructions`, `permission`, and `model`.
+
+This keeps benchmark and orchestration runs reproducible while still allowing
+provider configuration and `opencode auth` credentials to work. Project-level
+config discovered from the workspace is not suppressed.
+
+Set `inherit_user_config=True` to restore the legacy behavior of inheriting the
+host OpenCode config as-is. For reproducible runs, pass `model`, `permission`,
+`mcp`, `tools`, and `instructions` explicitly through `RunConfig`.
+
 ## CLI arguments
 
 `RunConfig` maps to flags such as `--agent`, `-m`, `-f`, `--attach`, `--title`, etc. Prompt text is appended as the final `opencode run` message argument.

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/py_opencode_wrapper.egg-info/SOURCES.txt

@@ -19,4 +19,5 @@ tests/test_integration_instructions.py
 tests/test_integration_multi_agent_weather.py
 tests/test_integration_opencode.py
 tests/test_integration_parallel.py
-tests/test_run_result_fuzzy_text.py
+tests/test_run_result_fuzzy_text.py
+tests/test_user_config_isolation.py

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "py-opencode-wrapper"
-version = "0.1.5"
+version = "0.2.1"
 description = "Async Python wrapper for OpenCode CLI (opencode run --format json)"
 readme = "README.md"
 requires-python = ">=3.8"

{py_opencode_wrapper-0.1.5 → py_opencode_wrapper-0.2.1}/tests/test_client_async.py

@@ -57,6 +57,23 @@ def test_build_env_config_content_and_autoupdate() -> None:
     assert env.get("OPENCODE_DISABLE_AUTOUPDATE") == "1"
 
 
+def test_build_env_sets_pwd_to_cwd() -> None:
+    """opencode's run.ts:276 reads `process.env.PWD ?? process.cwd()` to
+    resolve the project root, and the bash builtin pwd reads $PWD.
+    asyncio.create_subprocess_exec(cwd=...) only chdirs the child; PWD stays
+    inherited from the parent shell.  build_env must pin PWD to the workspace
+    so opencode and bash both see a consistent cwd."""
+    cfg = RunConfig()
+    env = build_env(cfg, base={"HOME": "/tmp", "PWD": "/some/other/dir"}, cwd="/ws/x")
+    assert env["PWD"] == "/ws/x"
+
+
+def test_build_env_without_cwd_leaves_pwd_untouched() -> None:
+    cfg = RunConfig()
+    env = build_env(cfg, base={"HOME": "/tmp", "PWD": "/parent"})
+    assert env["PWD"] == "/parent"
+
+
 @pytest.mark.asyncio
 async def test_readline_unlimited_normal_line() -> None:
     """Lines within the default 64 KiB limit are returned as-is."""

py_opencode_wrapper-0.2.1/tests/test_user_config_isolation.py

@@ -0,0 +1,442 @@
+"""Tests for the ``inherit_user_config`` flag and global-config sanitisation."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from opencode_wrapper.client import (
+    AsyncOpenCodeClient,
+    _isolate_user_config,
+    _sanitize_and_copy,
+)
+from opencode_wrapper.config import (
+    PRESERVE_KEYS,
+    RunConfig,
+    loads_jsonc,
+    sanitize_user_config_json,
+    strip_jsonc,
+)
+
+
+# ---------------------------------------------------------------------------
+# sanitize_user_config_json
+# ---------------------------------------------------------------------------
+
+
+def test_sanitize_user_config_json_drops_capability_keys() -> None:
+    raw = {
+        "$schema": "https://opencode.ai/config.json",
+        "provider": {"openai": {"api_base": "https://example/v1"}},
+        "disabled_providers": ["anthropic"],
+        "enabled_providers": ["openai"],
+        "model": "anthropic/claude-haiku-4-5",
+        "small_model": "anthropic/claude-haiku-4-5",
+        "default_agent": "build",
+        "mcp": {"my_server": {"command": "uvx", "args": ["my-mcp"]}},
+        "agent": {"my_agent": {"description": "..."}},
+        "mode": {"plan": {"tools": {"bash": False}}},
+        "command": {"my_cmd": {"description": "..."}},
+        "skills": ["~/.opencode/skills"],
+        "plugin": ["my_plugin"],
+        "tools": {"bash": True},
+        "formatter": {"py": "ruff format"},
+        "lsp": {"go": {"command": ["gopls"]}},
+        "instructions": ["AGENTS.md"],
+        "permission": {"bash": "deny"},
+        "experimental": {"primary_tools": ["bash"]},
+        "watcher": {"ignore": ["dist"]},
+        "share": "disabled",
+        "autoupdate": False,
+        "username": "alice",
+        "shell": "bash",
+        "logLevel": "DEBUG",
+    }
+    out = sanitize_user_config_json(raw)
+    assert set(out.keys()) == {
+        "$schema",
+        "provider",
+        "disabled_providers",
+        "enabled_providers",
+    }
+    assert out["provider"] == {"openai": {"api_base": "https://example/v1"}}
+
+
+def test_sanitize_user_config_json_passthrough_when_empty() -> None:
+    assert sanitize_user_config_json({}) == {}
+
+
+def test_preserve_keys_contains_only_provider_set() -> None:
+    """Guard against accidental scope creep in PRESERVE_KEYS."""
+    assert PRESERVE_KEYS == frozenset(
+        {"$schema", "provider", "disabled_providers", "enabled_providers"}
+    )
+
+
+# ---------------------------------------------------------------------------
+# strip_jsonc / loads_jsonc
+# ---------------------------------------------------------------------------
+
+
+def test_strip_jsonc_strips_line_comments() -> None:
+    out = strip_jsonc('// header\n{"a": 1} // tail\n')
+    assert json.loads(out) == {"a": 1}
+
+
+def test_strip_jsonc_strips_block_comments() -> None:
+    out = strip_jsonc('/* leading */ {"a": /* inline */ 1}')
+    assert json.loads(out) == {"a": 1}
+
+
+def test_strip_jsonc_strips_trailing_commas_in_objects() -> None:
+    out = strip_jsonc('{"a": 1, "b": 2,}')
+    assert json.loads(out) == {"a": 1, "b": 2}
+
+
+def test_strip_jsonc_strips_trailing_commas_in_arrays() -> None:
+    out = strip_jsonc('[1, 2, 3,]')
+    assert json.loads(out) == [1, 2, 3]
+
+
+def test_strip_jsonc_preserves_comment_syntax_inside_strings() -> None:
+    src = '{"url": "https://x.com/path", "note": "/* not a comment */"}'
+    out = strip_jsonc(src)
+    parsed = json.loads(out)
+    assert parsed == {"url": "https://x.com/path", "note": "/* not a comment */"}
+
+
+def test_strip_jsonc_handles_escaped_quotes_in_strings() -> None:
+    src = r'{"s": "she said \"hi // there\""}'
+    out = strip_jsonc(src)
+    assert json.loads(out) == {"s": 'she said "hi // there"'}
+
+
+def test_strip_jsonc_preserves_commas_inside_values() -> None:
+    """Commas that aren't immediately before } or ] are left alone."""
+    src = '{"a": 1, "b": 2}'
+    assert strip_jsonc(src) == '{"a": 1, "b": 2}'
+
+
+def test_strip_jsonc_handles_trailing_comma_before_close_after_comment() -> None:
+    """Trailing comma followed by a comment then } still recognised as trailing."""
+    out = strip_jsonc('{"a": 1, /* x */ }')
+    assert json.loads(out) == {"a": 1}
+
+
+def test_loads_jsonc_fast_path_for_strict_json() -> None:
+    """Strict JSON parses on the fast path (no JSONC stripping)."""
+    assert loads_jsonc('{"a": 1}') == {"a": 1}
+
+
+def test_loads_jsonc_handles_real_jsonc() -> None:
+    assert loads_jsonc('// hi\n{"a": 1,}') == {"a": 1}
+
+
+def test_loads_jsonc_raises_on_garbage() -> None:
+    with pytest.raises(json.JSONDecodeError):
+        loads_jsonc("this is not json")
+
+
+# ---------------------------------------------------------------------------
+# _sanitize_and_copy
+# ---------------------------------------------------------------------------
+
+
+def test_sanitize_and_copy_writes_filtered_json(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "opencode.json").write_text(
+        json.dumps({"provider": {"openai": {}}, "mcp": {"x": {}}, "model": "m"}),
+        encoding="utf-8",
+    )
+    dst = tmp_path / "dst"
+
+    _sanitize_and_copy(src, dst)
+
+    out = json.loads((dst / "opencode.json").read_text(encoding="utf-8"))
+    assert out == {"provider": {"openai": {}}}
+
+
+def test_sanitize_and_copy_missing_source_dir_creates_empty_dst(tmp_path: Path) -> None:
+    dst = tmp_path / "dst"
+    _sanitize_and_copy(tmp_path / "does_not_exist", dst)
+    assert dst.is_dir()
+    assert list(dst.iterdir()) == []
+
+
+def test_sanitize_and_copy_jsonc_with_comments_and_trailing_commas(
+    tmp_path: Path,
+) -> None:
+    """JSONC superset (line/block comments + trailing commas) is supported."""
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "opencode.jsonc").write_text(
+        """// header
+        {
+          "provider": {
+            "openai": {
+              "api_base": "X", /* inline */
+            },
+          },
+          "mcp": {"x": {}},
+        }
+        """,
+        encoding="utf-8",
+    )
+    dst = tmp_path / "dst"
+    _sanitize_and_copy(src, dst)
+    out = json.loads((dst / "opencode.jsonc").read_text(encoding="utf-8"))
+    assert out == {"provider": {"openai": {"api_base": "X"}}}
+
+
+def test_sanitize_and_copy_truly_unparseable_skipped(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Files that are neither JSON nor JSONC are skipped with a warning."""
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "opencode.jsonc").write_text("this is not json at all", encoding="utf-8")
+    dst = tmp_path / "dst"
+    with caplog.at_level(logging.WARNING, logger="opencode_wrapper.client"):
+        _sanitize_and_copy(src, dst)
+    assert not (dst / "opencode.jsonc").exists()
+    assert any("not parseable" in r.message for r in caplog.records)
+
+
+def test_sanitize_and_copy_jsonc_without_comments_succeeds(tmp_path: Path) -> None:
+    """Pure-JSON .jsonc files are sanitised and preserved by filename."""
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "opencode.jsonc").write_text(
+        json.dumps({"provider": {"openai": {}}, "mcp": {"x": {}}}),
+        encoding="utf-8",
+    )
+    dst = tmp_path / "dst"
+    _sanitize_and_copy(src, dst)
+    out = json.loads((dst / "opencode.jsonc").read_text(encoding="utf-8"))
+    assert out == {"provider": {"openai": {}}}
+
+
+def test_sanitize_and_copy_non_object_root_skipped(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "opencode.json").write_text("[]", encoding="utf-8")
+    dst = tmp_path / "dst"
+    with caplog.at_level(logging.WARNING, logger="opencode_wrapper.client"):
+        _sanitize_and_copy(src, dst)
+    assert not (dst / "opencode.json").exists()
+    assert any("root is not a JSON object" in r.message for r in caplog.records)
+
+
+# ---------------------------------------------------------------------------
+# _isolate_user_config
+# ---------------------------------------------------------------------------
+
+
+def test_isolate_user_config_sets_xdg_and_test_home(tmp_path: Path) -> None:
+    fake_home = tmp_path / "real_home"
+    (fake_home / ".config" / "opencode").mkdir(parents=True)
+    (fake_home / ".config" / "opencode" / "opencode.json").write_text(
+        json.dumps({"provider": {"openai": {}}, "mcp": {"x": {}}}),
+        encoding="utf-8",
+    )
+    (fake_home / ".opencode").mkdir(parents=True)
+    (fake_home / ".opencode" / "opencode.json").write_text(
+        json.dumps({"provider": {"anthropic": {}}, "agent": {"a": {}}}),
+        encoding="utf-8",
+    )
+    tmp_root = tmp_path / "iso"
+    tmp_root.mkdir()
+
+    env = {"HOME": str(fake_home), "OPENCODE_CONFIG": "/leak", "OPENCODE_CONFIG_DIR": "/leak"}
+    out = _isolate_user_config(env, tmp_root)
+
+    assert out["XDG_CONFIG_HOME"] == str(tmp_root / "xdg")
+    assert out["OPENCODE_TEST_HOME"] == str(tmp_root / "home")
+    assert "OPENCODE_CONFIG" not in out
+    assert "OPENCODE_CONFIG_DIR" not in out
+
+    xdg_cfg = json.loads(
+        (tmp_root / "xdg" / "opencode" / "opencode.json").read_text(encoding="utf-8")
+    )
+    assert xdg_cfg == {"provider": {"openai": {}}}
+    home_cfg = json.loads(
+        (tmp_root / "home" / ".opencode" / "opencode.json").read_text(encoding="utf-8")
+    )
+    assert home_cfg == {"provider": {"anthropic": {}}}
+
+
+def test_isolate_user_config_honours_explicit_xdg_config_home(tmp_path: Path) -> None:
+    custom_xdg = tmp_path / "custom_xdg"
+    (custom_xdg / "opencode").mkdir(parents=True)
+    (custom_xdg / "opencode" / "opencode.json").write_text(
+        json.dumps({"provider": {"p": {}}, "mcp": {"x": {}}}),
+        encoding="utf-8",
+    )
+    tmp_root = tmp_path / "iso"
+    tmp_root.mkdir()
+
+    env = {"HOME": "/nonexistent", "XDG_CONFIG_HOME": str(custom_xdg)}
+    out = _isolate_user_config(env, tmp_root)
+
+    assert out["XDG_CONFIG_HOME"] == str(tmp_root / "xdg")
+    cfg = json.loads(
+        (tmp_root / "xdg" / "opencode" / "opencode.json").read_text(encoding="utf-8")
+    )
+    assert cfg == {"provider": {"p": {}}}
+
+
+# ---------------------------------------------------------------------------
+# Default flag + end-to-end env wiring through async_run
+# ---------------------------------------------------------------------------
+
+
+def test_run_config_default_inherit_user_config_is_false() -> None:
+    assert RunConfig().inherit_user_config is False
+
+
+class _CapturedEnvProc:
+    """Fake subprocess that records the env it was spawned with."""
+
+    def __init__(self) -> None:
+        self.stdout = _OneShotStdout(b'{"type":"text","content":"ok"}\n')
+        self.stderr = _EmptyStream()
+        self.returncode: int | None = 0
+
+    async def wait(self) -> int:
+        return 0
+
+
+class _OneShotStdout:
+    def __init__(self, line: bytes) -> None:
+        self._line: bytes | None = line
+
+    async def readline(self) -> bytes:
+        await asyncio.sleep(0)
+        if self._line is None:
+            return b""
+        out, self._line = self._line, None
+        return out
+
+    async def readuntil(self, sep: bytes = b"\n") -> bytes:
+        return await self.readline()
+
+    async def readexactly(self, n: int) -> bytes:
+        raise AssertionError("unused")
+
+
+class _EmptyStream:
+    async def readline(self) -> bytes:
+        await asyncio.sleep(0)
+        return b""
+
+    async def readuntil(self, sep: bytes = b"\n") -> bytes:
+        await asyncio.sleep(0)
+        return b""
+
+    async def readexactly(self, n: int) -> bytes:
+        raise AssertionError("unused")
+
+
+@pytest.mark.asyncio
+async def test_async_run_default_isolates_user_config(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """By default, the env passed to opencode redirects XDG_CONFIG_HOME and OPENCODE_TEST_HOME."""
+    fake_home = tmp_path / "real_home"
+    (fake_home / ".config" / "opencode").mkdir(parents=True)
+    (fake_home / ".config" / "opencode" / "opencode.json").write_text(
+        json.dumps({"provider": {"o": {}}, "mcp": {"x": {}}}), encoding="utf-8"
+    )
+    monkeypatch.setenv("HOME", str(fake_home))
+    monkeypatch.setenv("OPENCODE_CONFIG", "/leak/path")
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+
+    captured: dict[str, dict[str, str]] = {}
+
+    async def fake_exec(*args, **kwargs):
+        captured["env"] = dict(kwargs["env"])
+        return _CapturedEnvProc()
+
+    client = AsyncOpenCodeClient(
+        binary="opencode", isolate_db=False, startup_delay_s=0
+    )
+    monkeypatch.setattr(client, "resolved_binary", lambda: "/fake/opencode")
+
+    with patch("asyncio.create_subprocess_exec", new=fake_exec):
+        await client.async_run("hi", tmp_path, run_cfg=RunConfig())
+
+    env = captured["env"]
+    assert "XDG_CONFIG_HOME" in env
+    assert env["XDG_CONFIG_HOME"] != str(fake_home / ".config")
+    assert "oc_cfg_" in env["XDG_CONFIG_HOME"]
+    assert "OPENCODE_TEST_HOME" in env
+    assert "oc_cfg_" in env["OPENCODE_TEST_HOME"]
+    assert "OPENCODE_CONFIG" not in env
+
+
+@pytest.mark.asyncio
+async def test_async_run_default_writes_sanitised_global_config(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """The sanitised opencode.json under the isolated XDG is visible to the child env."""
+    fake_home = tmp_path / "real_home"
+    (fake_home / ".config" / "opencode").mkdir(parents=True)
+    (fake_home / ".config" / "opencode" / "opencode.json").write_text(
+        json.dumps({"provider": {"openai": {"api_base": "X"}}, "mcp": {"x": {}}}),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("HOME", str(fake_home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+
+    seen: dict[str, dict] = {}
+
+    async def fake_exec(*args, **kwargs):
+        env = kwargs["env"]
+        cfg_path = Path(env["XDG_CONFIG_HOME"]) / "opencode" / "opencode.json"
+        seen["cfg"] = json.loads(cfg_path.read_text(encoding="utf-8"))
+        return _CapturedEnvProc()
+
+    client = AsyncOpenCodeClient(binary="opencode", isolate_db=False, startup_delay_s=0)
+    monkeypatch.setattr(client, "resolved_binary", lambda: "/fake/opencode")
+
+    with patch("asyncio.create_subprocess_exec", new=fake_exec):
+        await client.async_run("hi", tmp_path, run_cfg=RunConfig())
+
+    assert seen["cfg"] == {"provider": {"openai": {"api_base": "X"}}}
+
+
+@pytest.mark.asyncio
+async def test_async_run_inherit_true_does_not_mutate_xdg_config_home(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """Setting inherit_user_config=True keeps the inherited XDG_CONFIG_HOME / HOME."""
+    fake_home = tmp_path / "real_home"
+    fake_home.mkdir()
+    monkeypatch.setenv("HOME", str(fake_home))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(fake_home / ".config"))
+
+    captured: dict[str, dict[str, str]] = {}
+
+    async def fake_exec(*args, **kwargs):
+        captured["env"] = dict(kwargs["env"])
+        return _CapturedEnvProc()
+
+    client = AsyncOpenCodeClient(binary="opencode", isolate_db=False, startup_delay_s=0)
+    monkeypatch.setattr(client, "resolved_binary", lambda: "/fake/opencode")
+
+    with patch("asyncio.create_subprocess_exec", new=fake_exec):
+        await client.async_run(
+            "hi", tmp_path, run_cfg=RunConfig(inherit_user_config=True)
+        )
+
+    env = captured["env"]
+    assert env.get("XDG_CONFIG_HOME") == str(fake_home / ".config")
+    assert "OPENCODE_TEST_HOME" not in env