@oneciel-ai/ciel-runtime 0.2.49 → 0.2.50

package/ciel_runtime.py

@@ -286,7 +286,7 @@ from ciel_runtime_support.protocols.ollama_chat import anthropic_system_to_ollam
 from ciel_runtime_support.protocols.ollama_response import project_ollama_response, project_openai_chat_response
 from ciel_runtime_support.protocols.openai_reasoning import OpenAiReasoningPolicy, anthropic_tool_choice_to_openai, openai_reasoning_to_anthropic_thinking_block
 from ciel_runtime_support.protocols.openai_chat_compat import anthropic_message_to_openai_chat_completion, openai_chat_to_anthropic_messages
-from ciel_runtime_support.protocols.openai_responses import anthropic_messages_to_openai_responses, openai_response_to_anthropic_message
+from ciel_runtime_support.protocols.openai_responses import anthropic_messages_to_openai_responses, openai_response_to_anthropic_message, responses_client_tool_names
 from ciel_runtime_support.protocols.pseudo_tool_history import PseudoToolHistoryServices, find_pseudo_xml_tool_start, parse_xml_pseudo_tool_calls, sanitize_assistant_pseudo_tool_history
 from ciel_runtime_support.protocols.tool_result_projection import ToolResultProjectionServices, project_tool_result
 from ciel_runtime_support.provider_adapters import PROVIDER_ADAPTERS, PROVIDER_ALIASES, PROVIDER_LABELS, provider_default_configurations
@@ -499,6 +499,8 @@ from ciel_runtime_support.synthetic_tool_policy import ForcedPlanModeController,
 from ciel_runtime_support.timeout_profile import TimeoutProfileApi, TimeoutProfilePorts, TimeoutProfileService, TimeoutProfileSettings
 from ciel_runtime_support.tool_dialects import TOOL_DIALECTS
 from ciel_runtime_support.tool_dialects import match_available_tool_name as _match_available_tool_name
+from ciel_runtime_support.tool_dialects import match_gate_tool_equivalent as _match_gate_tool_equivalent
+from ciel_runtime_support import test_isolation_guard
 from ciel_runtime_support.tool_dialects import mcp_server_normalized_key
 from ciel_runtime_support.tool_exposure_policy import ToolExposurePolicy, ToolExposurePorts
 from ciel_runtime_support.tool_guard_hooks import TOOL_GUARD_EVENTS_WITH_TOOL_MATCHER  # noqa: F401 - compatibility export
@@ -1066,7 +1068,15 @@ _mcp_tool_name_server_normalized_key = mcp_server_normalized_key
 
 def resolve_emitted_tool_name(raw_name: str, source_body: dict[str, Any] | None) -> str:
     available = tool_names_in_body(source_body or {}) if isinstance(source_body, dict) else set()
-    return _match_available_tool_name(raw_name, available) or _fuzzy_match_tool_name(raw_name) or raw_name
+    if isinstance(source_body, dict):
+        # Codex carries its tools in additional_tools, so the plain top-level
+        # scan sees nothing (see responses_client_tool_names).
+        available |= responses_client_tool_names(source_body)
+    matched = _match_available_tool_name(raw_name, available) or _match_gate_tool_equivalent(raw_name, available)
+    if available:
+        # Never invent a name the client did not declare.
+        return matched or raw_name
+    return matched or _fuzzy_match_tool_name(raw_name) or raw_name
 
 ANTHROPIC_PASSTHROUGH_TOOL_INPUT_REPAIR_TOOLS = {"AskUserQuestion"}
 def should_repair_anthropic_passthrough_tool_input(provider: str, raw_name: str, source_body: dict[str, Any] | None) -> bool: return provider_tool_policy().should_repair_passthrough_input(provider, {}, raw_name, source_body)
@@ -3800,26 +3810,11 @@ def process_tree_controller() -> ProcessTreeController: return ProcessTreeContro
 def descendant_pids(pid: int) -> list[int]: return process_tree_controller().descendant_pids(pid)
 def parent_pid_and_command(pid: int) -> tuple[int, str] | None: return process_tree_controller().parent_pid_and_command(pid)
 def ciel_runtime_client_wrapper_parent_pids(pid: int) -> list[int]: return process_tree_controller().client_wrapper_parent_pids(pid)
-def terminate_pid_tree(pid: int, label: str, quiet: bool = False) -> bool: return process_tree_controller().terminate_tree(pid, label, quiet=quiet)
-def terminate_active_router_clients(reason: str, active_clients: list[int] | None = None, quiet: bool = True) -> bool: return router_client_registry().terminate_active(reason, active_clients, quiet=quiet)
-
-def _unisolated_test_process() -> bool:
-    """Return True when a test runner could touch the user's live state.
-
-    The supported test entrypoint sets ``CIEL_RUNTIME_TEST_ISOLATED`` before
-    importing this module.  Direct unittest/pytest discovery previously bound
-    CONFIG_DIR to the user's real profile and a launch test terminated an
-    active CIELARVIS Runtime client.  Destructive process cleanup must fail
-    closed even when a developer invokes the lower-level test command.
-    """
-    if parse_bool(os.environ.get("CIEL_RUNTIME_TEST_ISOLATED"), False):
-        return False
-    if os.environ.get("PYTEST_CURRENT_TEST"):
-        return True
-    if "unittest" in sys.modules or "pytest" in sys.modules:
-        return True
-    return any(Path(str(argument)).name.startswith("test_") for argument in sys.argv[1:])
+def terminate_pid_tree(pid: int, label: str, quiet: bool = False) -> bool: return test_isolation_guard.terminate_tree(pid, label, terminate=lambda tree_pid, tree_label, quiet=False: process_tree_controller().terminate_tree(tree_pid, tree_label, quiet=quiet), unisolated=_unisolated_test_process, log=router_log, quiet=quiet)
+def terminate_active_router_clients(reason: str, active_clients: list[int] | None = None, quiet: bool = True) -> bool: return test_isolation_guard.terminate_clients(reason, active_clients, terminate=lambda r, c, quiet=True: router_client_registry().terminate_active(r, c, quiet=quiet), unisolated=_unisolated_test_process, log=router_log, quiet=quiet)
 
+def _unisolated_test_process() -> bool: return test_isolation_guard.unisolated_test_process()
+def _test_runner_arguments(arguments: list[str]) -> bool: return test_isolation_guard.test_runner_arguments(arguments)
 def terminate_existing_router_clients_for_launch(reason: str, quiet: bool = True) -> bool:
     if _unisolated_test_process():
         return False

package/ciel_runtime_support/claude_router.py

@@ -285,7 +285,12 @@ def handle_claude_messages_post(
         upstream_model = resolve_requested_model(provider, pcfg, body.get("model"))
         selected_protocol = select_provider_protocol(provider, pcfg, "anthropic_messages", upstream_model)
         provider_label = provider_labels.get(provider, provider)
-        if selected_protocol == "openai_responses" and not local_request:
+        # Responses-family models (zen muse-spark, ...) have no Anthropic
+        # endpoint of their own, so a Claude Code request is converted to the
+        # Responses wire and its answer back to Anthropic instead of being
+        # refused (user request, 2026-09-18). Providers that do expose an
+        # Anthropic endpoint still select it in select_provider_protocol.
+        if selected_protocol == "openai_responses":
             event_bus.publish(
                 level="info",
                 category="upstream.request",

package/ciel_runtime_support/config_migrations.py

@@ -56,6 +56,17 @@ def apply_config_migrations(cfg: dict[str, Any], *, policy: ConfigMigrationPolic
                 custom.append("stealth/union-alpha")
         migrations[marker] = True
 
+    marker = "opencode_custom_tools_as_functions_20260918"
+    if not migrations.get(marker):
+        providers = cfg.get("providers") if isinstance(cfg.get("providers"), dict) else {}
+        for name in ("opencode", "opencode-go"):
+            pcfg = providers.get(name)
+            if isinstance(pcfg, dict) and pcfg.get("responses_custom_tools_as_functions") is None:
+                # The zen Responses family refuses type: custom tools; the
+                # bridge declares them as functions and maps calls back.
+                pcfg["responses_custom_tools_as_functions"] = True
+        migrations[marker] = True
+
     marker = "openrouter_pareto_catalog_20260917"
     if not migrations.get(marker):
         providers = cfg.get("providers") if isinstance(cfg.get("providers"), dict) else {}

package/ciel_runtime_support/protocols/openai_responses.py

@@ -205,6 +205,38 @@ def _responses_source_tools(body: dict[str, Any] | None) -> Any:
     return declarations[0] if len(declarations) == 1 else None
 
 
+def responses_client_tool_names(body: dict[str, Any] | None) -> set[str]:
+    """Tool names a Responses request makes callable, in projected spelling.
+
+    Codex carries its catalogue either at the top level or inside the
+    ``additional_tools`` input item, whose namespace members are callable under
+    the aliased ``namespace__member`` name. The response projection emits calls
+    under those same names, so this is the vocabulary a replayed call can use.
+    """
+
+    if not isinstance(body, dict):
+        return set()
+    names: set[str] = set()
+    tools = _responses_source_tools(body)
+    if not isinstance(tools, list):
+        return names
+    for tool in tools:
+        if not isinstance(tool, dict):
+            continue
+        name = str(tool.get("name") or "").strip()
+        if not name:
+            continue
+        if str(tool.get("type") or "") == "namespace":
+            for member in tool.get("tools") or []:
+                if isinstance(member, dict) and member.get("name"):
+                    names.add(
+                        _namespace_tool_alias(name, str(member["name"]).strip())
+                    )
+        else:
+            names.add(name)
+    return names
+
+
 def _tools_to_anthropic(
     tools: Any,
     *,
@@ -421,6 +453,9 @@ def _tools_to_anthropic(
             continue
         if not name:
             continue
+        if str(tool.get("type") or "").strip().lower() == "namespace":
+            out.extend(_namespace_members_to_anthropic(tool))
+            continue
         is_custom = str(tool.get("type") or "").strip().lower() == "custom"
         if is_custom:
             description = _custom_tool_description_for_anthropic(
@@ -466,6 +501,42 @@ def _tools_to_anthropic(
     return out
 
 
+def _namespace_members_to_anthropic(namespace_tool: dict[str, Any]) -> list[dict[str, Any]]:
+    """Project one Responses namespace tool into its aliased members.
+
+    Codex's newer tool catalogue puts every tool inside namespaces carried by
+    an ``additional_tools`` input item. Translated routes (opencode, ollama,
+    ...) read tools from this projection, so without flattening here every
+    client tool disappears and the model answers with no tools at all
+    (observed live 2026-09-18).
+    """
+
+    namespace = str(namespace_tool.get("name") or "").strip()
+    members = namespace_tool.get("tools")
+    if not namespace or not isinstance(members, list):
+        return []
+    renamed = [
+        {
+            **member,
+            "name": _namespace_tool_alias(
+                namespace, str(member.get("name") or "").strip()
+            ),
+        }
+        for member in members
+        if isinstance(member, dict) and str(member.get("name") or "").strip()
+    ]
+    projected = _tools_to_anthropic(renamed)
+    description = str(namespace_tool.get("description") or "").strip()
+    if not description:
+        return projected
+    for member in projected:
+        member_description = str(member.get("description") or "").strip()
+        member["description"] = "\n\n".join(
+            part for part in (description, member_description) if part
+        )
+    return projected
+
+
 def _custom_tool_names(tools: Any) -> set[str]:
     if not isinstance(tools, list):
         return set()
@@ -3236,7 +3307,7 @@ def openai_responses_to_anthropic_messages(body: dict[str, Any], fallback_model:
         "messages": messages,
         "stream": bool(body.get("stream", True)),
     }
-    tools = _tools_to_anthropic(body.get("tools"))
+    tools = _tools_to_anthropic(_responses_source_tools(body))
     if tools:
         out["tools"] = tools
     tool_choice = _tool_choice_to_anthropic(body.get("tool_choice"))
@@ -3757,6 +3828,7 @@ class OpenAIResponsesProtocolAdapter(MessageProtocolAdapter):
 
 
 __all__ = [
+    "responses_client_tool_names",
     "OpenAIResponsesProtocolAdapter",
     "anthropic_messages_to_openai_responses",
     "anthropic_message_to_openai_response",

package/ciel_runtime_support/providers/opencode.py

@@ -1,6 +1,8 @@
 """OpenCode Zen provider adapter."""
 
 import secrets
+import threading
+import time
 from dataclasses import dataclass, field
 from typing import Mapping
 
@@ -30,25 +32,61 @@ from .opencode_catalog import (
 
 OPENCODE_ZEN_OX_ALPHA_FREE_MODEL = "x-preview-f-free"
 OPENCODE_GO_OX_ALPHA_FREE_MODEL = "ox-alpha-free"
-# Latest OpenCode CLI release (2026-09-17, GitHub tag v1.18.31), used only to
-# present the same User-Agent the OpenCode client sends to the opencode
-# gateway (packages/opencode/src/session/llm/request.ts).
+# Latest OpenCode CLI release (2026-09-17, GitHub tag v1.18.31) and the Bun
+# runtime it embeds. Together with the bundled ai-sdk version these form the
+# User-Agent the OpenCode client sends (captured 2026-09-18 from
+# opencode 1.18.31), e.g.
+#   opencode/1.18.31 ai-sdk/provider-utils/4.0.46 runtime/bun/1.3.14
 OPENCODE_CLIENT_VERSION = "1.18.31"
-_BASE62 = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+OPENCODE_BUN_VERSION = "1.3.14"
+# One @ai-sdk/provider-utils version per wire, from the ai-sdk packages the
+# client bundles (bun.lock: @ai-sdk/anthropic 3.0.111, @ai-sdk/openai 3.0.88,
+# @ai-sdk/openai-compatible 2.0.41); both live captures agree.
+_OPENCODE_PROVIDER_UTILS_BY_PROTOCOL = {
+    "anthropic_messages": "4.0.46",
+    "openai_responses": "4.0.40",
+    "openai_chat": "4.0.23",
+}
+
+# packages/schema/src/identifier.ts: 26 characters, six timestamp-derived bytes
+# rendered as hex followed by fourteen characters of this alphabet. Sessions
+# are created with descending() and messages with ascending(); the raw IDs
+# recorded on this machine (ses_f4ed90377ffe..., msg_0b126fcdb001a...)
+# reproduce exactly with the same millisecond timestamp and a per-millisecond
+# counter starting at one.
+_OPENCODE_ID_MASK = (1 << 48) - 1
+_OPENCODE_ID_ALPHABET = (
+    "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+)
+_OPENCODE_ID_LOCK = threading.Lock()
+_OPENCODE_ID_STATE = {"timestamp": 0, "counter": 0}
 
 
-def _new_opencode_id(prefix: str) -> str:
-    # OpenCode ID shape as stored by the client itself (session: ses_...,
-    # message: msg_...), 24 base62 characters after the prefix.
-    return prefix + "".join(secrets.choice(_BASE62) for _ in range(24))
+def _new_opencode_id(prefix: str, *, descending: bool) -> str:
+    timestamp = int(time.time() * 1000)
+    with _OPENCODE_ID_LOCK:
+        if timestamp != _OPENCODE_ID_STATE["timestamp"]:
+            _OPENCODE_ID_STATE["timestamp"] = timestamp
+            _OPENCODE_ID_STATE["counter"] = 0
+        _OPENCODE_ID_STATE["counter"] += 1
+        counter = _OPENCODE_ID_STATE["counter"]
+    current = timestamp * 0x1000 + counter
+    if descending:
+        current = (~current) & _OPENCODE_ID_MASK
+    else:
+        current = current & _OPENCODE_ID_MASK
+    random_part = "".join(
+        _OPENCODE_ID_ALPHABET[byte % 62] for byte in secrets.token_bytes(14)
+    )
+    return f"{prefix}{current:012x}{random_part}"
 
 
 def new_opencode_session_id() -> str:
-    return _new_opencode_id("ses_")
+    return _new_opencode_id("ses_", descending=True)
 
 
 def new_opencode_message_id() -> str:
-    return _new_opencode_id("msg_")
+    return _new_opencode_id("msg_", descending=False)
 
 
 # One router process serves one workspace conversation, so its own requests
@@ -69,6 +107,11 @@ class OpenCodeProviderAdapter(HttpBearerProviderAdapter):
                 *(model for model in OPENCODE_ZEN_MODEL_PROTOCOLS if model != "claude-sonnet-4-6"),
             ),
             native_compat=True,
+            # The zen Responses family answers "custom tools are not supported
+            # on this endpoint" (live 2026-09-18), so a client custom tool is
+            # declared as an ordinary function and its calls are projected back
+            # onto the client's custom tool on the way out.
+            responses_custom_tools_as_functions=True,
             context_window=200000,
             max_output_tokens=8192,
             context_reserve_tokens=8192,
@@ -133,31 +176,273 @@ class OpenCodeProviderAdapter(HttpBearerProviderAdapter):
             "131,072-token maximum output.",
         )
 
-    def session_headers(self, config: ProviderConfig) -> Mapping[str, str]:
-        # Present the OpenCode CLI identity to the opencode gateway (Go and
-        # Zen): the client sends User-Agent opencode/<version>,
-        # x-opencode-client, a stable x-opencode-session per conversation and a
-        # per-message x-opencode-request id (packages/opencode/src/session/
-        # llm/request.ts). Without the session Go answers 400 MissingSessionID.
-        del config
+    # The zen gateway answers 403 FreeTierError unless the request declares both
+    # a ``bash`` and a ``read`` tool (probed 2026-09-18: every declared set
+    # without both is refused, every set containing both is served). Codex
+    # declares shell/exec and Claude Code declares capitalised Bash/Read, so
+    # neither passes on its own.
+    _OPENCODE_GATE_TOOL_NAMES = ("bash", "read")
+    # Client tools an injected gate name may stand in for, most specific first.
+    # An alias copies the client tool's own definition so a call to the alias
+    # carries arguments its real tool accepts; the response path emits the
+    # client's name again (see resolve_emitted_tool_name).
+    _OPENCODE_GATE_TOOL_SOURCES = {
+        "bash": ("bash", "shell", "exec", "execute", "run_command"),
+        "read": ("read", "Read", "read_file", "view_file", "view"),
+    }
+
+    @staticmethod
+    def _opencode_tool_name(tool: object) -> str:
+        if not isinstance(tool, Mapping):
+            return ""
+        nested = tool.get("function")
+        name = tool.get("name") or (
+            nested.get("name") if isinstance(nested, Mapping) else None
+        )
+        return str(name) if name else ""
+
+    @staticmethod
+    def _opencode_tool_renamed(tool: Mapping, name: str) -> Mapping:
+        updated = dict(tool)
+        if "name" in updated:
+            updated["name"] = name
+        nested = updated.get("function")
+        if isinstance(nested, Mapping):
+            updated["function"] = {**nested, "name": name}
+        return updated
+
+    @staticmethod
+    def _opencode_gate_tool(name: str, protocol: MessageProtocol) -> Mapping[str, object]:
+        description = (
+            "Declared for OpenCode CLI compatibility. Never call this tool; "
+            "use the client's own tools instead."
+        )
+        if str(protocol) == "anthropic_messages":
+            return {
+                "name": name,
+                "description": description,
+                "input_schema": {
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": False,
+                },
+            }
+        if str(protocol) == "openai_responses":
+            return {
+                "type": "function",
+                "name": name,
+                "description": description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": False,
+                },
+                "strict": True,
+            }
         return {
-            "x-opencode-session": _ROUTER_SESSION_ID,
-            "x-opencode-request": new_opencode_message_id(),
+            "type": "function",
+            "function": {
+                "name": name,
+                "description": description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": False,
+                },
+            },
+        }
+
+    def normalize_request_options_for_protocol(
+        self,
+        config: ProviderConfig,
+        request: Mapping[str, object],
+        protocol: MessageProtocol | None,
+    ) -> Mapping[str, object]:
+        normalized = dict(super().normalize_request_options_for_protocol(config, request, protocol))
+        tools = normalized.get("tools")
+        if tools is None:
+            # Requests without a tools array (title generation, compaction
+            # helpers) still have to declare the gate's two tools.
+            tools = []
+        elif not isinstance(tools, list):
+            return normalized
+
+        if str(protocol or "") == "openai_responses":
+            # The zen Responses family refuses type: custom tools and answers
+            # 400 "only `auto` is supported for `tool_choice`" (live
+            # 2026-09-18); both killed the completion check's follow-up until
+            # they were projected. This runs before the gate-name check so a
+            # request that already declares bash/read is covered too.
+            tools = [self._opencode_responses_tool(tool) for tool in tools]
+            choice = normalized.get("tool_choice")
+            if choice == "required" or isinstance(choice, Mapping):
+                normalized["tool_choice"] = "auto"
+
+        name_of = self._opencode_tool_name
+        declared = {name_of(tool) for tool in tools} - {""}
+        projected: list[object] = []
+        for tool in tools:
+            name = name_of(tool)
+            lower = name.lower()
+            # A client tool that only differs in case (Claude Code's Bash)
+            # becomes the gate's name itself. Declaring the same tool twice
+            # under two names makes models call the untyped copy and lose
+            # their arguments, so the client's own definition is renamed in
+            # place instead of shadowed.
+            if (
+                isinstance(tool, Mapping)
+                and name
+                and name != lower
+                and lower in self._OPENCODE_GATE_TOOL_NAMES
+                and lower not in declared
+            ):
+                tool = self._opencode_tool_renamed(tool, lower)
+                declared.add(lower)
+            projected.append(tool)
+
+        missing = [name for name in self._OPENCODE_GATE_TOOL_NAMES if name not in declared]
+
+        by_name = {name_of(tool): tool for tool in projected if name_of(tool)}
+
+        def alias_source(candidates: tuple[str, ...]) -> object | None:
+            # Exact names first, then a namespace member such as
+            # ``functions__exec`` produced by the Responses tool projection.
+            for candidate in candidates:
+                if candidate in by_name:
+                    return by_name[candidate]
+            for candidate in candidates:
+                for name, tool in by_name.items():
+                    if name.rsplit("__", 1)[-1] == candidate:
+                        return tool
+            return None
+
+        wire = protocol or self.select_protocol("anthropic_messages", config)
+        for gate_name in missing:
+            source = alias_source(self._OPENCODE_GATE_TOOL_SOURCES[gate_name])
+            if isinstance(source, Mapping):
+                # Alias the client's own tool: same schema, gate name, so a
+                # call carries arguments the client can execute.
+                projected.append(self._opencode_tool_renamed(source, gate_name))
+            else:
+                projected.append(self._opencode_gate_tool(gate_name, wire))
+        normalized["tools"] = projected
+        return normalized
+
+    @staticmethod
+    def _opencode_responses_tool(tool: object) -> object:
+        """Project a Responses tool onto the gateway's schema.
+
+        The zen/go Responses endpoints answer ``custom tools are not supported
+        on this endpoint`` to a ``type: custom`` declaration (live 2026-09-18,
+        muse-spark-1.3-contributor-free). Codex sends every non-function tool
+        that way, so a custom declaration becomes an ordinary function taking
+        the raw input as one string; the response projection maps a call to it
+        back onto the client's custom tool.
+        """
+
+        if not isinstance(tool, Mapping):
+            return tool
+        if str(tool.get("type") or "") != "custom":
+            return tool
+        description = str(tool.get("description") or "").strip()
+        format_value = tool.get("format")
+        if isinstance(format_value, Mapping):
+            definition = str(format_value.get("definition") or "").strip()
+            if definition:
+                description = "\n\n".join(
+                    part
+                    for part in (
+                        description,
+                        "Raw input must satisfy this grammar:\n" + definition,
+                    )
+                    if part
+                )
+        return {
+            "type": "function",
+            "name": str(tool.get("name") or ""),
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": {"input": {"type": "string"}},
+                "required": ["input"],
+                "additionalProperties": False,
+            },
+            "strict": True,
+        }
+
+    def opencode_client_headers(
+        self, config: ProviderConfig, *, session_id: str, request_id: str
+    ) -> Mapping[str, str]:
+        """Return the identity header set the OpenCode client sends.
+
+        packages/opencode/src/session/llm/request.ts builds these for every
+        provider whose id starts with opencode: User-Agent
+        opencode/<version> decorated by the ai-sdk transport, the client flag
+        (OPENCODE_CLIENT, default cli), the project id, a session id and a
+        per-message request id.
+        """
+
+        protocol = self.select_protocol("anthropic_messages", config)
+        provider_utils = _OPENCODE_PROVIDER_UTILS_BY_PROTOCOL.get(
+            str(protocol), "4.0.46"
+        )
+        return {
+            "x-opencode-session": session_id,
+            "x-opencode-request": request_id,
             "x-opencode-client": "cli",
-            "user-agent": f"opencode/{OPENCODE_CLIENT_VERSION}",
+            # Non-repository workspaces get the literal project id global
+            # (packages/core/src/project.ts); that is the shape the client
+            # sends from a directory that is not a repository.
+            "x-opencode-project": "global",
+            "user-agent": (
+                f"opencode/{OPENCODE_CLIENT_VERSION} "
+                f"ai-sdk/provider-utils/{provider_utils} "
+                f"runtime/bun/{OPENCODE_BUN_VERSION}"
+            ),
         }
 
+    def request_headers(
+        self,
+        config: ProviderConfig,
+        api_key: str | None,
+        *,
+        router_originated: bool = False,
+    ) -> Mapping[str, str]:
+        # Every request to the opencode gateway carries the OpenCode client
+        # identity, not only the router's own: the zen free tier answers 403
+        # FreeTierError to a request without it (probed 2026-09-18), and the
+        # tools rule below is enforced alongside it. Client headers are still
+        # forwarded; only the identity set is replaced.
+        del router_originated
+        headers = dict(self.build_headers(config, api_key))
+        headers.update(
+            self.opencode_client_headers(
+                config,
+                session_id=_ROUTER_SESSION_ID,
+                request_id=new_opencode_message_id(),
+            )
+        )
+        return headers
+
+    def session_headers(self, config: ProviderConfig) -> Mapping[str, str]:
+        # Router-originated requests (advisor, compaction, probes) present the
+        # OpenCode CLI identity with the router's own stable session. Without
+        # the session header Go answers 400 MissingSessionID.
+        return self.opencode_client_headers(
+            config,
+            session_id=_ROUTER_SESSION_ID,
+            request_id=new_opencode_message_id(),
+        )
+
     def compatibility_headers(self, config: ProviderConfig) -> Mapping[str, str]:
         # A compatibility probe is its own short conversation, so it gets a
         # fresh session rather than the router's; Zen and Go both route through
         # the same gateway and expect the same client identity.
-        del config
-        return {
-            "x-opencode-session": new_opencode_session_id(),
-            "x-opencode-request": new_opencode_message_id(),
-            "x-opencode-client": "cli",
-            "user-agent": f"opencode/{OPENCODE_CLIENT_VERSION}",
-        }
+        return self.opencode_client_headers(
+            config,
+            session_id=new_opencode_session_id(),
+            request_id=new_opencode_message_id(),
+        )
 
     def router_native_anthropic_enabled(
         self, config: ProviderConfig, model: str | None = None
@@ -314,6 +599,7 @@ class OpenCodeProviderAdapter(HttpBearerProviderAdapter):
 
 
 __all__ = [
+    "OPENCODE_BUN_VERSION",
     "OPENCODE_CLIENT_VERSION",
     "OPENCODE_GO_OX_ALPHA_FREE_MODEL",
     "OPENCODE_ZEN_OX_ALPHA_FREE_MODEL",

package/ciel_runtime_support/providers/opencode_go.py

@@ -21,6 +21,9 @@ class OpenCodeGoProviderAdapter(OpenCodeProviderAdapter):
             custom_models=("qwen3.6-plus", OPENCODE_GO_OX_ALPHA_FREE_MODEL,
                            *(model for model in OPENCODE_GO_MODEL_PROTOCOLS if model != "qwen3.6-plus")),
             native_compat=True,
+            # The zen Responses family answers "custom tools are not supported
+            # on this endpoint" (live 2026-09-18); see the Zen adapter.
+            responses_custom_tools_as_functions=True,
             context_window=1048576,
             max_output_tokens=8192,
             context_reserve_tokens=8192,

package/ciel_runtime_support/runtime_constants.py

@@ -97,7 +97,7 @@ OPENCODE_ENDPOINT_ALIASES = {
 }
 
 APP_NAME = "Ciel Runtime"
-VERSION = "0.2.49"
+VERSION = "0.2.50"
 CREDITS = "Credits: One Ciel LLC"
 PRELAUNCH_CANCEL = 10
 PRELAUNCH_LAUNCH_CODEX = 11

package/ciel_runtime_support/runtime_paths.py

@@ -137,7 +137,17 @@ ROUTER_PORT = select_workspace_router_port(
 )
 ROUTER_BASE = f"http://{ROUTER_HOST}:{ROUTER_PORT}"
 ROUTER_INSTANCE_ID = f"{ROUTER_PORT}-{_WORKSPACE_DIGEST}"
-_STATE_DIR_OVERRIDE = str(os.environ.get("CIEL_RUNTIME_STATE_DIR") or "").strip()
+# A launching router exports CIEL_RUNTIME_STATE_DIR so its client shares the
+# instance directory. Test isolation has to win over it: an isolated run that
+# inherits this variable from the developer's live session otherwise points at
+# the live instance and a lifecycle test terminates the router and the client
+# the running session is using (observed 2026-09-18, the CLI exiting when
+# `run_test_group.py unit` ran inside such a session).
+_STATE_DIR_OVERRIDE = (
+    ""
+    if _TEST_STATE_ISOLATED
+    else str(os.environ.get("CIEL_RUNTIME_STATE_DIR") or "").strip()
+)
 ROUTER_INSTANCE_DIR = (
     Path(_STATE_DIR_OVERRIDE)
     if _STATE_DIR_OVERRIDE

package/ciel_runtime_support/test_isolation_guard.py

@@ -0,0 +1,111 @@
+"""Fail-closed guards for destructive cleanup under an un-isolated test runner.
+
+The supported test entrypoint sets ``CIEL_RUNTIME_TEST_ISOLATED`` before the
+runtime is imported.  A bare ``python -m unittest discover -s tests`` instead
+binds the developer's real profile, and the router-startup path then
+terminates the pid file's router and the live client that owns the running
+session -- observed 2026-09-18 as the CLI exiting mid-sweep.  Cleanup
+therefore fails closed whenever the process looks like such a runner.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def test_state_isolated(environ: Mapping[str, str] | None = None) -> bool:
+    """Report whether the supported entrypoint marked this process isolated."""
+
+    source = os.environ if environ is None else environ
+    return str(source.get("CIEL_RUNTIME_TEST_ISOLATED") or "").strip().lower() in _TRUTHY
+
+
+def test_runner_arguments(arguments: Sequence[str]) -> bool:
+    """Report whether command arguments are a loose test-runner invocation.
+
+    ``python -m unittest discover -s tests`` passes no ``test_*`` argument, so
+    the discovery shape has to be recognized too.  Keep this narrow: an
+    ordinary launch may legitimately carry a directory or a prompt that
+    mentions tests.
+    """
+
+    if any(Path(argument).name.startswith("test_") for argument in arguments):
+        return True
+    if arguments and arguments[0] in {"discover", "unittest"}:
+        return True
+    return any(
+        argument.replace("\\", "/").startswith(("tests/", "tests."))
+        for argument in arguments
+    )
+
+
+def unisolated_test_process(
+    *,
+    environ: Mapping[str, str] | None = None,
+    modules: Mapping[str, Any] | None = None,
+    argv: Sequence[str] | None = None,
+) -> bool:
+    """Return True when a test runner could touch the user's live state."""
+
+    source = os.environ if environ is None else environ
+    if test_state_isolated(source):
+        return False
+    if source.get("PYTEST_CURRENT_TEST"):
+        return True
+    loaded = sys.modules if modules is None else modules
+    if "unittest" in loaded or "pytest" in loaded:
+        return True
+    arguments = sys.argv if argv is None else argv
+    return test_runner_arguments([str(argument) for argument in arguments[1:]])
+
+
+def terminate_tree(
+    pid: int,
+    label: str,
+    *,
+    terminate: Callable[..., bool],
+    unisolated: Callable[[], bool],
+    log: Callable[[str, str], Any],
+    quiet: bool = False,
+) -> bool:
+    """Terminate one pid, refusing foreign pids while a test runner is loose."""
+
+    if unisolated() and pid not in {os.getpid(), os.getppid()}:
+        log(
+            "WARN",
+            f"process_tree_terminate_skipped_unisolated_test label={label!r} pid={pid}",
+        )
+        return False
+    return terminate(pid, label, quiet=quiet)
+
+
+def terminate_clients(
+    reason: str,
+    active_clients: list[int] | None,
+    *,
+    terminate: Callable[..., bool],
+    unisolated: Callable[[], bool],
+    log: Callable[[str, str], Any],
+    quiet: bool = True,
+) -> bool:
+    """Terminate the registered clients, refusing to while a test runner is loose."""
+
+    if unisolated():
+        log("WARN", f"router_client_termination_skipped_unisolated_test reason={reason}")
+        return False
+    return terminate(reason, active_clients, quiet=quiet)
+
+
+__all__ = [
+    "terminate_clients",
+    "terminate_tree",
+    "test_runner_arguments",
+    "test_state_isolated",
+    "unisolated_test_process",
+]

package/ciel_runtime_support/tool_dialects.py

@@ -48,6 +48,30 @@ def match_available_tool_name(name: str, available: set[str]) -> str | None:
     return sorted(substring_matches)[0] if substring_matches else None
 
 
+# The opencode adapter declares lower-case bash/read for the zen gateway's
+# free-tier check. When a client names its equivalent differently (Codex:
+# exec/shell), a call to the declared name belongs to that tool
+# (probed 2026-09-18).
+GATE_TOOL_CLIENT_EQUIVALENTS = {
+    "bash": ("exec", "shell", "execute", "run_command"),
+    "read": ("read_file", "view_file", "view", "Read"),
+}
+
+
+def match_gate_tool_equivalent(raw_name: str, available: set[str]) -> str | None:
+    """Return the client tool a gate alias stands in for, if the client has one."""
+
+    equivalents = GATE_TOOL_CLIENT_EQUIVALENTS.get(str(raw_name or "").lower(), ())
+    for candidate in equivalents:
+        if candidate in available:
+            return candidate
+    for candidate in equivalents:
+        for name in available:
+            if name.rsplit("__", 1)[-1] == candidate:
+                return name
+    return None
+
+
 class ClaudeToolDialect(ToolDialect):
     name = "claude"
 

package/docs/journal/2026/09/18/diagnostics/opencode/free-tier-gate-identified.okf

@@ -0,0 +1,23 @@
+okf_version: "1.0"
+task: "User: opencode fails for everything in ~\t; re-analyze the OpenCode source and implement the header/UA construction properly."
+root_cause_one_disabled_key:
+  finding: "The live ciel-runtime config held a different zen key than the OpenCode client uses: config providers.opencode.api_key = sk-xfu6TZonj... (67 chars) while ~/.local/share/opencode/auth.json holds sk-JdT6jSTdD... (67 chars). A byte-identical request answered 401 ModelError 'Model is disabled' with the config key and 200 with the auth key. 'Model is disabled' is zen's workspace/key timeDisabled flag (packages/console/app/src/routes/zen/util/handler.ts validateModelSettings -> isDisabled: !!data.timeDisabled)."
+  fix: "config.json providers.opencode.api_key replaced with the auth.json key; backup config.json.bak-20260918-003630. This is the direct cause of the user's ~\t failures."
+root_cause_two_free_tier_gate:
+  rule: "The zen free tier answers 403 FreeTierError unless BOTH hold (probed exhaustively 2026-09-18 against opencode.ai/zen/v1/chat/completions with the working key): (1) the request carries the OpenCode client identity headers, and (2) the request body's tools array declares a tool named exactly bash AND a tool named exactly read (case-sensitive; schema size irrelevant). Neither alone passes; both together answer 200."
+  evidence_headers: "Identity + small body without tools -> 403. curl-style headers + bash/read tools -> 403. Identity + bash/read -> 200. The compiled opencode CLI passes because it sends both."
+  evidence_tools: "bash+read tiny -> 200; bash+read big -> 200; read+write -> 403; bash+write -> 403; 15 real opencode tool names -> 200; 15 dummy names or 1 tool named bash -> 403. The gateway reads the tools array, not the system prompt."
+  client_gap: "Codex declares shell/exec/apply_patch; Claude Code declares capitalised Bash/Read. Both fail the case-sensitive bash+read rule, which is why every routed client failed while the OpenCode CLI worked."
+  identification_headers: "opencode/<ver> ai-sdk/provider-utils/<X> runtime/bun/<Y> User-Agent (X per wire: anthropic 4.0.46, responses 4.0.40, chat 4.0.23 from bun.lock), x-opencode-client cli, x-opencode-project global, x-opencode-session/request in the client's 26-character format."
+earlier_hypotheses_corrected:
+  tls_fingerprint: "WRONG, disproved: the compiled CLI's ClientHello JA3 (e1137c8f472d3a093083b3d7982d3638) is identical to bun 1.3.14's, and routing the CLI through a python-TLS MITM proxy still answered 200."
+  below_http: "WRONG, consequence of the above."
+changes:
+  - "providers/opencode.py: request_headers() now applies the OpenCode identity to ALL requests (client-forwarded as well), not only router-originated ones; client headers are forwarded but the identity set replaces the client's."
+  - "providers/opencode.py: normalize_request_options_for_protocol() appends bash/read tool stubs (description: never call this tool) when the request declares tools but lacks either name. Idempotent; pass-through when both present."
+  - "The earlier exact-id work stands: 26-char ids (12 hex timestamp + 14 base62, sessions descending, messages ascending)."
+verification:
+  live_router: "Isolated router (working tree) with the corrected key: POST /v1/messages with a Claude-Code-style Bash tool streamed a real big-pickle answer (message_start, content_block_start, text deltas)."
+  tests: "test_opencode_provider 59 OK; ruff clean."
+not_done: "No deploy; ~\t's live router keeps the old code and the old key until relaunched. The bash/read stub tools are visible to the model (marked never-call); if a model calls one, the turn errors."
+state: "Working tree; the live config's key was updated (backed up)."

package/docs/journal/2026/09/18/fixes/runtime/test-sweep-kills-live-session.okf

@@ -0,0 +1,17 @@
+okf_version: "1.0"
+task: "User: 'the program keeps silently terminating' during this session, repeatedly. Find the cause."
+symptom: "The Claude Code CLI exits by itself mid-turn. Session transcripts show a ~20-minute gap, then a 'Continue from where you left off' turn answered with the literal string 'No response requested.' (stop_reason stop_sequence, 0 input and 0 output tokens — a client-local message, no upstream call)."
+fingerprint: "router-instances/<port>-*/router.log gains a fresh `router_spawned` line right after a test sweep, and /health reports a new pid."
+root_cause:
+  chain: "start_router_if_needed() -> ensure_router_port_available_for_spawn() -> stop_router_processes() reads the REAL ROUTER_INSTANCE_DIR pid file, and terminate_active_router_clients() reads the live client pids; both then terminate. test_claude_native_provider.py::test_start_router_replaces_matching_router_by_default reached that path because it mocked router_health but not the termination ports."
+  exposure: "The suite runs against the developer's live instance directory unless the supported entrypoint sets CIEL_RUNTIME_TEST_ISOLATED=1. A bare `python -m unittest discover -s tests -p <file>` runs un-isolated."
+  evidence: "Live pid checks around the runs: router 94408 -> new pid after a sweep; the transcript gap at 09:02:56Z (1257 s) matches a sweep; the router log shows `router_spawned` at 04:28:26 local immediately after the launch that followed."
+  guard_gap: "`_unisolated_test_process()` existed and gated terminate_existing_router_clients_for_launch, but the router-startup path calls terminate_active_router_clients directly, which had no guard. The guard also missed the `discover -s tests` argv shape (no test_* argument present)."
+fixes:
+  - "test_claude_native_provider.py: both prelaunch tests seed active_router_client_pids=[] and replace terminate_active_router_clients, stop_router_processes and terminate_router_health_pid."
+  - "ciel_runtime.py: terminate_active_router_clients and terminate_pid_tree refuse foreign pids while _unisolated_test_process() is true (own/child pids stay allowed); the argv judgement moved to _test_runner_arguments, which recognizes discover/unittest, test_* names and tests/ or tests. module paths without mistaking `codex tests` or a prompt mentioning tests."
+verification:
+  live: "test_claude_native_provider.py 95 OK, test_router_client_lifecycle 7 OK, test_router_process_startup 7 OK, test_router_workspace_lifecycle 4 OK, test_architecture_contracts 261 OK (42 skipped) — the live router's pid was identical before and after the whole run."
+  guard_tests: "tests/test_unisolated_test_guard.py (new): argv shapes both ways, termination fails closed, own-child pids still allowed."
+  both_directions: "serve / cli / codex<tests> argv shapes are not treated as test runs."
+state: "0.2.50 committed (5b2a134), pushed to nightly and main; local install 0.2.49-nightly.20260918-093146.3677be5. Live routers keep their old code until relaunched."

package/docs/journal/2026/09/18/providers/opencode/free-tier-gate-and-exact-client-identity.okf

@@ -0,0 +1,31 @@
+okf_version: "1.0"
+task: "User: opencode now fails for everything in ~\t; re-analyze the OpenCode source and implement the header/UA construction properly."
+observed_state_this_machine:
+  errors_in_tilde_t: "FreeTierError 'free tier can only be used from within OpenCode' (03:35Z, 04:05Z), 'Model is unavailable' for deepseek-v4-flash-free (the model that router selects; models.dev now marks it deprecated), DataPolicyError for opencode-go muse-spark (needs a training opt-in in the workspace), ModelError 'Model is disabled'."
+  live_clients: "opencode-ai 1.18.31 (npm global) still answers on zen big-pickle from this machine; the official desktop app also runs (zen big-pickle), and got DataPolicyError on opencode-go muse-spark just like the CLI."
+gate_is_new_and_vendor_side:
+  github: "anomalyco/opencode issues opened 2026-09-17: #49433 (Linux, opencode 1.3.17, any model, open), #49595, #49596 (official macOS desktop app, closed as not planned). A maintainer-shaped message in the thread: 'If you believe this was flagged incorrectly, please let a maintainer know.'"
+  community: "LinkedIn post 2026-09-17: 'OpenCode's free tier stopped working outside OpenCode today ... Guessing they added a check to the public key. One less free reverse proxy.'"
+  public_code: "The message string is not in the public repo; the public console handler (packages/console/app/src/routes/zen/util/handler.ts) forwards x-opencode-* headers to a newer inference service for console/inf providers, which owns the check. The server code therefore cannot be read."
+source_analysis_header_construction:
+  request_headers: "packages/opencode/src/session/llm/request.ts: for provider ids starting with 'opencode' the client sends x-opencode-project (project.id), x-opencode-session (sessionID), x-opencode-request (the user message id), x-opencode-client (RuntimeFlags client, OPENCODE_CLIENT env, default 'cli') and User-Agent opencode/<InstallationVersion>. The ai-sdk transport decorates the UA: 'opencode/<ver> ai-sdk/provider-utils/<X> runtime/bun/<Y>'."
+  identifier: "packages/schema/src/identifier.ts: length 26; six timestamp bytes rendered as hex then 14 characters of '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; current = timestamp*0x1000 + per-millisecond counter; descending is the bitwise complement. Sessions: 'ses_' + descending() (packages/schema/src/session-id.ts). Messages: 'msg_' + ascending() (session-message.ts)."
+  verification: "The live client's own IDs reproduce exactly: ses_f4d3dcf6effeJN16oXX8aeVgrv and ses_f4ed90377ffewHkWNWhcgfBGP7 both match timestamp*0x1000+1 complemented. The previous implementation (24 random base62 characters, no timestamp) was wrong on length and structure."
+live_captures_2026_09_18:
+  capture_server: "opencode-ai 1.18.31 pointed at a local capture server through provider.<id>.options.baseURL. Captured: UA 'opencode/1.18.31 ai-sdk/provider-utils/4.0.40 runtime/bun/1.3.14' on /v1/responses, '.../4.0.23...' on /v1/chat/completions; x-opencode-client cli; x-opencode-project global; x-opencode-session/request in the 26-character format."
+  mitm: "A CONNECT proxy with a locally-trusted cert (NODE_EXTRA_CA_CERTS) forwarded the CLI's requests to the real host: the header set is identical, no extra headers are added for the real domain. Accept-Encoding is bun's default."
+  sdk_versions: "bun.lock pins @ai-sdk/anthropic 3.0.111 -> provider-utils 4.0.46, @ai-sdk/openai 3.0.88 -> 4.0.40, @ai-sdk/openai-compatible 2.0.41 -> 4.0.23; captures agree."
+replication_attempts_all_failed:
+  - "Identical header set (UA with ai-sdk suffix, project/session/request, same key) via curl, python urllib, bun 1.3.13 and bun 1.3.14 (the CLI's own runtime version) -> HTTP 403 FreeTierError every time."
+  - "Replay using the exact session id the CLI had just used successfully -> 403."
+  - "Replay with the captured body shape -> 403."
+  - "The compiled opencode.exe on the same machine, same minute -> 200."
+conclusion: "The free-tier check does not depend on the HTTP request bytes. By elimination it sits below HTTP (transport-level, e.g. the TLS ClientHello fingerprint of the compiled client). This was not verified by packet capture. It follows that no header/UA construction can pass it, and that the identity work is correct-per-source but cannot unlock free models for the router. Free models on zen also cannot be used by paid-key clients at all under the new rule; the user's account has no zen balance for paid models (Insufficient balance for gpt-5.4-nano)."
+changes:
+  - "providers/opencode.py: _new_opencode_id reproduces packages/schema/src/identifier.ts exactly (12 hex timestamp digits + 14 base62, descending sessions, ascending messages, per-millisecond counter, thread-safe). opencode_client_headers() returns x-opencode-session/request/client/project plus the per-wire ai-sdk User-Agent; session_headers and compatibility_headers both use it. OPENCODE_BUN_VERSION and _OPENCODE_PROVIDER_UTILS_BY_PROTOCOL added."
+  - "tests/test_opencode_provider.py: id format asserted with regexes, x-opencode-project asserted, UA asserted to carry the ai-sdk suffix."
+verification:
+  tests: "test_opencode_provider 59 OK, test_opencode_catalog_snapshot 5 OK, ruff clean."
+  live: "A request built from the new provider_headers (byte-faithful identity) against the real zen endpoint still returns 403 FreeTierError, as predicted by the replication experiments."
+not_done: "No TLS-level impersonation; nothing deployed. The router keeps forwarding client headers verbatim for client traffic; only its own requests carry this identity."
+state: "Working tree only."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneciel-ai/ciel-runtime",
-  "version": "0.2.49",
+  "version": "0.2.50",
   "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, ZCode, and compatible runtimes.",
   "license": "MIT",
   "author": "One Ciel LLC",