uni-robot-agent-runtime 0.1.1__py3-none-any.whl

uni_robot_agent/__init__.py

@@ -0,0 +1,50 @@
+"""uni-robot-agent — A robot agent built on Codex and Claude Code."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+def _installed_version():
+    installed = {}
+    for name in ("uni-robot-agent", "uni-robot-agent-runtime"):
+        try:
+            installed[name] = version(name)
+        except PackageNotFoundError:
+            pass
+    if len(installed) > 1:
+        raise RuntimeError(
+            "uni-robot-agent and uni-robot-agent-runtime share module files and must be "
+            "installed in separate environments. Recreate this environment with only one package."
+        )
+    return next(iter(installed.values()), "unknown (not installed)")
+
+
+__version__ = _installed_version()
+
+
+# Keep version/help and record readers independent of planner and native runtimes.
+_EXPORTS = {
+    "SessionConfig": ("config", "SessionConfig"),
+    "AgentConfig": ("config", "AgentConfig"),
+    "Session": ("session", "Session"),
+    "run": ("session", "run_session"),
+    "ToolClient": ("tools.client", "ToolClient"),
+    "ToolJob": ("tools.client", "ToolJob"),
+    "ToolOutput": ("tools.toolkit", "ToolOutput"),
+    "RunResult": ("artifacts.records", "RunResult"),
+    "RunRecord": ("artifacts.records", "RunRecord"),
+    "SetupConfig": ("services.deployment.config", "SetupConfig"),
+    "DeploymentConfig": ("services.deployment.config", "DeploymentConfig"),
+    "Deployment": ("services.deployment.manager", "Deployment"),
+    "setup": ("services.deployment.setup", "setup"),
+    "deploy": ("services.deployment.manager", "start_deployment"),
+}
+__all__ = ["__version__", *_EXPORTS]
+
+
+def __getattr__(name):
+    if name not in _EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+    module, attribute = _EXPORTS[name]
+    value = getattr(import_module(f"{__name__}.{module}"), attribute)
+    globals()[name] = value
+    return value

uni_robot_agent/__main__.py

@@ -0,0 +1,5 @@
+"""Run uni-robot-agent from Python."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

uni_robot_agent/agents/__init__.py

@@ -0,0 +1,19 @@
+"""Agent contracts and lazy backend registration."""
+
+from .contracts import Agent, AgentCapabilities, AgentResult
+from .registry import (
+    create_agent,
+    get_agent_backend,
+    list_agent_backends,
+    register_agent,
+)
+
+__all__ = [
+    "Agent",
+    "AgentCapabilities",
+    "AgentResult",
+    "create_agent",
+    "get_agent_backend",
+    "list_agent_backends",
+    "register_agent",
+]

uni_robot_agent/agents/claude_code/__init__.py

@@ -0,0 +1,2 @@
+"""Claude Code agent plugin."""
+from .agent import ClaudeCodeAgent

uni_robot_agent/agents/claude_code/agent.py

@@ -0,0 +1,163 @@
+"""Claude Code SDK adapter; model transport and robot execution stay in uni-robot-agent."""
+from __future__ import annotations
+import asyncio
+from contextlib import aclosing
+import os
+from pathlib import Path
+import time
+from urllib.parse import urlsplit
+
+from uni_robot_agent.events import AgentRunStarted
+from uni_robot_agent.agents.contracts import AgentCapabilities, AgentResult
+from uni_robot_agent.agents.runtime import ModelRuntime
+from uni_robot_agent.provider.protocols.messages import MessagesProtocol
+from uni_robot_agent.provider.registry import build_provider_adapter
+from .artifacts import finalize_model_records
+from .config import ClaudeConfig
+from .events import ClaudeEvents
+from .model_binding import ClaudeModelBinding
+from .sdk_compat import mcp_description_env, context_env
+from .tools import ClaudeTools
+
+
+# Keep native computation and file access without unrelated coding-agent workflows.
+NATIVE_TOOLS = ("Bash", "Read", "Write", "Edit", "Glob", "Grep")
+
+
+class ClaudeCodeAgent(ClaudeConfig):
+    capabilities = AgentCapabilities()
+
+    def __init__(self, *, model="sonnet", timeout_s=None, cwd=None, api_key=None,
+                 max_budget_usd=None, effort=None):
+        self._model, self._cwd, self._api_key = model, cwd, api_key
+        self._budget, self._effort = max_budget_usd, effort
+        self._deadline = None if timeout_s is None else time.monotonic() + timeout_s
+        self._loop = self._task = None
+        self._cancel_reason = None
+        self._cleanup_error = None
+        self._binding = ClaudeModelBinding()
+
+    def model_runtime(self, profile, event_bus=None):
+        adapter = build_provider_adapter(profile, client_protocol=self.model_protocol)
+        self._binding = ClaudeModelBinding(event_bus)
+        return ModelRuntime("claude_messages", adapter, MessagesProtocol(keepalive_interval_s=60),
+                            self._binding, finalize_model_records)
+
+    def finalize_without_provider(self, result, session_dir):
+        if session_dir is not None:
+            result.train_error = "Claude native model records require --provider-url"
+
+    def cancel(self, reason):
+        self._cancel_reason = reason
+        self._binding.cancel()
+        if self._loop is not None and self._task is not None and not self._task.done():
+            self._loop.call_soon_threadsafe(self._task.cancel)
+
+    def close(self):
+        if self._cleanup_error:
+            raise RuntimeError(self._cleanup_error)
+        if self._task is not None and not self._task.done():
+            self.cancel("cancelled")
+            raise RuntimeError("Claude SDK run has not finished cleanup")
+
+    def run(self, *, prompt, task, toolkit, executor, max_turns=0,
+            event_bus=None, session_dir=None, model_endpoint=None):
+        try:
+            return asyncio.run(self._run_async(prompt, task, executor, max_turns,
+                                               event_bus, session_dir, model_endpoint))
+        finally:
+            self._loop = self._task = None
+
+    async def _run_async(self, prompt, task, executor, max_turns, bus, session_dir, model_endpoint):
+        import claude_agent_sdk as sdk
+        self._loop, self._task = asyncio.get_running_loop(), asyncio.current_task()
+        self._cancel_reason = None
+        tools = ClaudeTools(executor, self._binding, timeout_s=(
+            None if self._deadline is None else max(0, self._deadline - time.monotonic())
+        ))
+        state = ClaudeEvents(bus, self._binding)
+        started = time.monotonic()
+        cleanup_error = None
+        remaining = None if self._deadline is None else max(0, self._deadline - started)
+        deadline = asyncio.timeout(remaining)
+        try:
+            env = {
+                "CLAUDE_CODE_USE_BEDROCK": "0", "CLAUDE_CODE_USE_VERTEX": "0",
+                "CLAUDE_CODE_USE_FOUNDRY": "0", "CLAUDE_CODE_OAUTH_TOKEN": "",
+                "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+                # uni-robot-agent retries a complete buffered exchange, before tool delivery.
+                "CLAUDE_CODE_MAX_RETRIES": "0",
+                # Keep native helpers and subagents on the explicitly selected provider model.
+                "ANTHROPIC_DEFAULT_HAIKU_MODEL": self._model,
+                "ANTHROPIC_DEFAULT_SONNET_MODEL": self._model,
+                "ANTHROPIC_DEFAULT_OPUS_MODEL": self._model,
+                "CLAUDE_CODE_SUBAGENT_MODEL": self._model,
+                **mcp_description_env(tools.specs.values()),
+                **context_env(),
+            }
+            if model_endpoint:
+                env["ANTHROPIC_BASE_URL"] = model_endpoint.rstrip("/").removesuffix("/v1")
+                host = urlsplit(model_endpoint).hostname
+                bypass = ",".join(filter(None, [os.environ.get("NO_PROXY") or os.environ.get("no_proxy"), host]))
+                env.update(NO_PROXY=bypass, no_proxy=bypass)
+            token = self._api_key or os.environ.get("ANTHROPIC_AUTH_TOKEN")
+            if token:
+                env.update(ANTHROPIC_AUTH_TOKEN=token, ANTHROPIC_API_KEY="")
+            if session_dir is not None:
+                config_dir = Path(session_dir) / ".claude"
+                config_dir.mkdir(parents=True, exist_ok=True)
+                env["CLAUDE_CONFIG_DIR"] = str(config_dir.resolve())
+            options = sdk.ClaudeAgentOptions(
+                model=self._model, system_prompt=prompt.system,
+                max_turns=max_turns or None, max_budget_usd=self._budget,
+                max_buffer_size=64 * 1024 * 1024,
+                forward_subagent_text=True,
+                tools=list(NATIVE_TOOLS),
+                allowed_tools=["mcp__uni_robot_agent__" + name for name in tools.specs],
+                mcp_servers={"uni_robot_agent": tools.server()}, strict_mcp_config=True,
+                # The hook authorizes native tools, including access outside cwd.
+                # Root sessions use hook decisions rather than bypassPermissions.
+                permission_mode="dontAsk", sandbox={"enabled": False},
+                setting_sources=[], skills=[], cwd=self._cwd,
+                env=env, effort=self._effort,
+                hooks={
+                    "PreToolUse": [sdk.HookMatcher(hooks=[tools.pre_tool])],
+                    "PostToolUse": [sdk.HookMatcher(hooks=[tools.tool_completed])],
+                    "PostToolUseFailure": [sdk.HookMatcher(hooks=[tools.tool_failed])],
+                    "SubagentStart": [sdk.HookMatcher(hooks=[tools.subagent_event])],
+                    "SubagentStop": [sdk.HookMatcher(hooks=[tools.subagent_event])],
+                },
+            )
+            if bus:
+                bus.emit(AgentRunStarted(instruction=task, model=self._model,
+                                        agent_backend="claude_code", tool_event_source="execution"))
+            async with deadline:
+                async with aclosing(sdk.query(prompt=prompt.user, options=options)) as messages:
+                    async for message in messages:
+                        state.consume(message)
+        except asyncio.CancelledError:
+            state.stop_reason = self._cancel_reason or "cancelled"
+        except TimeoutError as error:
+            if deadline.expired():
+                state.stop_reason = "wall_time_limit"
+            else:
+                state.error = f"TimeoutError: {error}"
+        except Exception as error:
+            if not (state.stop_reason == "max_turns" and type(error).__name__ == "ResultError"):
+                state.error = f"{type(error).__name__}: {error}"
+        finally:
+            try:
+                await tools.close()
+            except Exception as error:
+                cleanup_error = self._cleanup_error = str(error)
+                state.error = state.error or cleanup_error
+        finish = state.finish_request
+        message = state.error or ((finish.get("summary") or finish.get("message")) if finish else None)
+        message = message or "\n".join(state.texts) or "Claude session ended without output"
+        return AgentResult(
+            success=finish is not None and state.completed and not state.error and not state.stop_reason,
+            message=message, error=state.error, cleanup_error=cleanup_error,
+            stop_reason=state.stop_reason, turns_used=state.turns, tool_calls=state.tool_calls,
+            steps_used=state.steps, elapsed_s=time.monotonic() - started,
+            main_thread_id=self._binding.thread_id, trace_format="claude_messages",
+        )

uni_robot_agent/agents/claude_code/artifacts.py

@@ -0,0 +1,29 @@
+"""Finalize Claude native model records without claiming Codex SFT compatibility."""
+from pathlib import Path
+
+from uni_robot_agent.events import ErrorEvent
+from uni_robot_agent.provider.recording.exchanges import get_model_exchange_error
+
+
+def finalize_model_records(gateway, result, session_dir, event_bus):
+    records = gateway.trace_records
+    result.provider_error = get_model_exchange_error(
+        records, interrupted=result.stop_reason in {"max_turns", "wall_time_limit", "cancelled"},
+    )
+    if result.provider_error:
+        result.error = result.error or result.provider_error
+        if event_bus:
+            event_bus.emit(ErrorEvent(message=result.provider_error))
+    if session_dir is not None:
+        result.provider_log_path = str(Path(session_dir) / "claude_messages")
+        result.train_error = "Claude native model exchanges are archived; provider-faithful SFT export is not implemented"
+    gateway.persist_report({
+        "trace_format": "claude_messages", "records_frozen": True,
+        "exchange_count": len(records), "provider_error": result.provider_error,
+        "agent_error": result.error, "stop_reason": result.stop_reason,
+        "main_thread_id": result.main_thread_id, "train_error": result.train_error,
+        "exchange_persistence_errors": [
+            {"index": item["index"], "error": item["persistence_error"]}
+            for item in records if item.get("persistence_error")
+        ],
+    })

uni_robot_agent/agents/claude_code/config.py

@@ -0,0 +1,50 @@
+"""Claude-only settings and validation of supported model services."""
+import os
+import argparse
+import math
+from urllib.parse import urlsplit
+
+
+class ClaudeConfig:
+    model_protocol = "messages"
+
+    @classmethod
+    def add_cli_arguments(cls, parser):
+        group = parser.add_argument_group("Claude Code SDK")
+        group.add_argument("--claude-max-budget-usd", type=float, default=argparse.SUPPRESS,
+                           help="Optional SDK cost ceiling; unset disables the SDK budget cap")
+        group.add_argument("--claude-effort", choices=("low", "medium", "high", "max"), default=argparse.SUPPRESS)
+
+    @classmethod
+    def resolve_defaults(cls, args):
+        args.claude_max_budget_usd = getattr(args, "claude_max_budget_usd", None)
+        args.claude_effort = getattr(args, "claude_effort", None)
+        if args.reasoning_effort is None:
+            args.reasoning_effort = "none"
+        if args.provider_url is None:
+            from uni_robot_agent.config import runtime_env
+            args.provider_url = runtime_env("PROVIDER_URL") or os.environ.get("ANTHROPIC_BASE_URL")
+
+    @classmethod
+    def validate_config(cls, args, explicit):
+        if "--codex-base-prompt" in explicit:
+            raise ValueError("--codex-base-prompt requires --agent codex")
+        if explicit & {"--mcp-parallel-dispatch", "--no-mcp-parallel-dispatch", "--mcp-timeout-s"}:
+            raise ValueError("Codex MCP dispatch options require --agent codex")
+        if args.reasoning_effort != "none":
+            raise ValueError("Use --claude-effort for Claude Code reasoning configuration")
+        if args.context_policy != "identity":
+            raise ValueError("Claude Code currently supports only identity context policy")
+        if not args.provider_url:
+            raise ValueError("Claude Code requires --provider-url or ANTHROPIC_BASE_URL")
+        if urlsplit(args.provider_url).scheme not in {"http", "https"}:
+            raise ValueError("Claude Messages provider URL must use HTTP or HTTPS")
+        if args.claude_max_budget_usd is not None and (
+            not math.isfinite(args.claude_max_budget_usd) or args.claude_max_budget_usd <= 0
+        ):
+            raise ValueError("--claude-max-budget-usd must be positive")
+
+    @classmethod
+    def config_options(cls, args):
+        return {"api_key": args._api_key, "max_budget_usd": args.claude_max_budget_usd,
+                "effort": args.claude_effort}

uni_robot_agent/agents/claude_code/events.py

@@ -0,0 +1,121 @@
+"""Claude SDK messages projected into uni-robot-agent events and terminal state."""
+import json
+from uni_robot_agent.events import AssistantText, ToolCall, ReasoningSummary, AgentActivity
+
+
+def get(value, key, default=None):
+    return value.get(key, default) if isinstance(value, dict) else getattr(value, key, default)
+
+
+def kind(value):
+    return str(value.get("type") or value.get("kind") or "") if isinstance(value, dict) else type(value).__name__
+
+
+def finish_succeeded(block):
+    if get(block, "is_error", False):
+        return False
+    for content in get(block, "content", []) or []:
+        if get(content, "type") != "text":
+            continue
+        try:
+            value = json.loads(get(content, "text", ""))
+        except ValueError:
+            continue
+        if isinstance(value, dict) and "call_ok" in value:
+            return value["call_ok"] is True and not value.get("error")
+    return False
+
+
+class ClaudeEvents:
+    def __init__(self, bus, binding):
+        self.bus, self.binding = bus, binding
+        self.turns = self.tool_calls = self.steps = 0
+        self.texts = []
+        self.seen_messages = set()
+        self.seen_calls = set()
+        self.finish_calls = {}
+        self.finish_request = None
+        self.completed = False
+        self.error = self.stop_reason = None
+        self.session_id = None
+
+    def emit(self, event):
+        if self.bus:
+            self.bus.emit(event)
+
+    def consume(self, message):
+        message_kind = kind(message)
+        parent_call = get(message, "parent_tool_use_id")
+        if parent_call:
+            # Tool hooks carry the authoritative child ID. Keep child prose
+            # separate from the main agent's completion and accounting.
+            agent_id, parent_agent_id = self.binding.child_identity(parent_call)
+            for block in get(message, "content", []) or []:
+                if kind(block) == "TextBlock" and get(block, "text"):
+                    self.emit(AgentActivity(kind="message", item_id=parent_call,
+                        agent_id=agent_id, parent_agent_id=parent_agent_id,
+                        label="subagent", text=get(block, "text")))
+            return
+        # TaskStartedMessage is a SystemMessage subclass with a distinct class name.
+        if get(message, "subtype") == "task_started":
+            data = get(message, "data", {})
+            agent_id = get(message, "task_id") or data.get("task_id")
+            parent_call = get(message, "tool_use_id") or data.get("tool_use_id")
+            if agent_id and parent_call:
+                self.binding.register_subagent(agent_id, parent_call)
+            return
+        if message_kind == "SystemMessage":
+            subtype = get(message, "subtype", "")
+            if subtype in {"init", "compact_boundary"}:
+                self.emit(AgentActivity(
+                    kind="started" if subtype == "init" else "compacted",
+                    agent_id=self.binding.thread_id, label="main",
+                    text=json.dumps(get(message, "data", {}).get("compact_metadata", {})),
+                ))
+            return
+        if message_kind == "AssistantMessage":
+            identity = get(message, "message_id")
+            if identity is None or identity not in self.seen_messages:
+                self.turns += 1
+                if identity:
+                    self.seen_messages.add(identity)
+            if get(message, "error"):
+                self.error = str(get(message, "error"))
+            for block in get(message, "content", []) or []:
+                if kind(block) == "TextBlock" and get(block, "text"):
+                    self.texts.append(get(block, "text"))
+                    self.steps += 1
+                    self.emit(AssistantText(text=get(block, "text"), agent_step=self.steps, turn=self.turns))
+                elif kind(block) == "ThinkingBlock" and get(block, "thinking"):
+                    self.emit(ReasoningSummary(text=get(block, "thinking")))
+                elif kind(block) == "ToolUseBlock":
+                    call_id = get(block, "id")
+                    if call_id in self.seen_calls:
+                        continue
+                    self.seen_calls.add(call_id)
+                    self.tool_calls += 1
+                    self.steps += 1
+                    name, arguments = get(block, "name", ""), get(block, "input", {})
+                    self.emit(ToolCall(tool_name=name, arguments=arguments, source_step=self.steps, turn=self.turns))
+                    if name in {"finish", "mcp__uni_robot_agent__finish"} and isinstance(arguments, dict):
+                        self.finish_calls[call_id] = arguments
+        elif message_kind == "UserMessage":
+            for block in get(message, "content", []) or []:
+                if kind(block) != "ToolResultBlock":
+                    continue
+                call_id = get(block, "tool_use_id")
+                self.binding.tool_result(call_id, failed=get(block, "is_error", False))
+                arguments = self.finish_calls.pop(call_id, None)
+                if arguments is not None and finish_succeeded(block):
+                    self.finish_request = arguments
+        elif message_kind == "ResultMessage":
+            self.session_id = get(message, "session_id")
+            subtype, reason = get(message, "subtype", ""), get(message, "terminal_reason")
+            self.completed = subtype == "success" and not get(message, "is_error", False) and reason in {None, "completed"}
+            if subtype == "error_max_turns":
+                self.stop_reason = "max_turns"
+            elif not self.completed:
+                if subtype == "error_max_budget_usd":
+                    self.stop_reason = "budget_limit"
+                details = get(message, "errors") or [get(message, "result") or reason or subtype]
+                self.error = f"Claude Agent SDK ended ({subtype}): {'; '.join(str(x) for x in details)}"

uni_robot_agent/agents/claude_code/model_binding.py

@@ -0,0 +1,163 @@
+"""Associate delivered model batches with exact Claude tool-use identities."""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from uuid import uuid4
+
+from uni_robot_agent.events import AgentActivity, ToolCallBatch
+from uni_robot_agent.provider.contracts import PreparedReply, RequestContext
+from uni_robot_agent.provider.protocols.messages import message_response
+
+
+@dataclass
+class Call:
+    name: str
+    arguments: dict
+    exchange_id: str
+    previous: str | None
+    delivered: bool = False
+    revoked: bool = False
+    claimed: bool = False
+    finished: bool = False
+    agent_id: str = ""
+    result_reported: bool = False
+
+
+class ClaudeModelBinding:
+    def __init__(self, event_bus=None):
+        self.thread_id = str(uuid4())
+        self.bus = event_bus
+        self.calls: dict[str, Call] = {}
+        self.messages: set[str] = set()
+        self.lock = threading.RLock()
+        self.cancelled = False
+        self.tool_names = None
+        self.batches: dict[str, PreparedReply] = {}
+        self.observed_batches: set[str] = set()
+        self.child_agents: dict[str, str] = {}
+        self.agent_parents: dict[str, str] = {}
+
+    def request_context(self, request):
+        # Messages requests do not carry a reliable child identity. Attribute
+        # tool exchanges from SDK hook IDs instead of labelling all requests main.
+        return RequestContext(metadata={"thread_id": self.thread_id, "thread_source": "claude_session"})
+
+    def prepare_response(self, body, exchange_id, metadata):
+        message = message_response(body)
+        calls = tuple({"call_id": block["id"], "name": block["name"], "arguments": block["input"]}
+                      for block in message.get("content", []) if block.get("type") == "tool_use")
+        with self.lock:
+            if any(call["call_id"] in self.calls for call in calls):
+                raise ValueError("Claude reused a tool-use ID across model exchanges")
+            previous = None
+            for call in calls:
+                self.calls[call["call_id"]] = Call(call["name"], call["arguments"], exchange_id, previous)
+                if self.tool_names is None or call["name"] in self.tool_names:
+                    previous = call["call_id"]
+        return PreparedReply(body, exchange_id, {**metadata, "turn_id": message.get("id", exchange_id)}, calls)
+
+    def response_written(self, reply):
+        with self.lock:
+            self.messages.add(reply.metadata["turn_id"])
+            self.batches[reply.exchange_id] = reply
+            for call in reply.tool_calls:
+                self.calls[call["call_id"]].delivered = True
+
+    def observe_call(self, call_id, agent_id):
+        """Use the SDK's explicit owner, never timing or argument matching."""
+        with self.lock:
+            call = self.calls.get(call_id)
+            if self.cancelled or call is None or call.revoked:
+                raise RuntimeError("Tool call has no active model exchange")
+            # The SDK can receive the bytes before the gateway's delivery callback.
+            # Do not allow native tools or MCP callbacks until delivery is confirmed.
+            if not call.delivered:
+                return False
+            reply = self.batches.get(call.exchange_id)
+            first = call.exchange_id not in self.observed_batches
+            self.observed_batches.add(call.exchange_id)
+            for item in reply.tool_calls:
+                candidate = self.calls[item["call_id"]]
+                if candidate.agent_id and candidate.agent_id != agent_id:
+                    raise ValueError("One Claude model response has conflicting tool owners")
+                candidate.agent_id = agent_id
+            parent = self.agent_parents.get(agent_id, "")
+            if self.bus:
+                if first:
+                    names = tuple(item["name"] for item in reply.tool_calls)
+                    self.bus.emit(AgentActivity(kind="tool_batch", agent_id=agent_id,
+                        parent_agent_id=parent, turn_id=reply.metadata["turn_id"],
+                        exchange_id=reply.exchange_id, tool_names=names, tool_calls=reply.tool_calls))
+                    if agent_id == self.thread_id:
+                        self.bus.emit(ToolCallBatch(batch_id=reply.exchange_id, tool_names=names, tool_calls=reply.tool_calls))
+                self.bus.emit(AgentActivity(kind="tool_started", agent_id=agent_id,
+                    parent_agent_id=parent, item_id=call_id, exchange_id=call.exchange_id,
+                    tool_names=(call.name,), tool_calls=({"call_id": call_id,
+                        "name": call.name, "arguments": call.arguments},)))
+            return True
+
+    def register_subagent(self, agent_id, parent_call_id):
+        """Link the SDK task ID to its exact spawning tool, including nested agents."""
+        with self.lock:
+            call = self.calls.get(parent_call_id)
+            if call is None or call.name not in {"Agent", "Task"} or not call.agent_id:
+                return
+            self.child_agents[parent_call_id] = agent_id
+            self.agent_parents[agent_id] = call.agent_id
+            if self.bus:
+                self.bus.emit(AgentActivity(kind="started", agent_id=agent_id,
+                    parent_agent_id=call.agent_id, item_id=parent_call_id, label="subagent"))
+
+    def child_identity(self, parent_call_id):
+        with self.lock:
+            call = self.calls.get(parent_call_id)
+            return self.child_agents.get(parent_call_id, ""), call.agent_id if call else ""
+
+    def tool_result(self, call_id, *, failed):
+        with self.lock:
+            call = self.calls.get(call_id)
+            if call is None:
+                return
+            # An SDK waiter ending does not stop an already claimed robot action.
+            if not call.claimed:
+                call.finished = True
+            if self.bus and not call.result_reported:
+                self.bus.emit(AgentActivity(kind="tool_failed" if failed else "tool_completed",
+                    agent_id=call.agent_id,
+                    parent_agent_id=self.agent_parents.get(call.agent_id, ""),
+                    item_id=call_id, exchange_id=call.exchange_id, tool_names=(call.name,),
+                    tool_calls=({"call_id": call_id, "name": call.name, "arguments": call.arguments},)))
+            call.result_reported = True
+
+    def response_failed(self, reply):
+        with self.lock:
+            for call in reply.tool_calls:
+                self.calls[call["call_id"]].revoked = True
+
+    def claim(self, call_id, name, arguments):
+        """Claim once, after delivery and preceding calls have acknowledged execution."""
+        with self.lock:
+            call = self.calls.get(call_id)
+            if self.cancelled or call is None or call.revoked:
+                raise RuntimeError("Tool call has no active, delivered model exchange")
+            if call.name != name or call.arguments != arguments:
+                raise ValueError("Tool callback differs from its model tool-use ID")
+            if name == "mcp__uni_robot_agent__finish" and call.agent_id != self.thread_id:
+                call.finished = True
+                raise PermissionError("Only the main agent may finish the episode; return findings to the parent")
+            if call.claimed:
+                raise RuntimeError("Duplicate Claude tool callback")
+            previous = self.calls.get(call.previous)
+            if not call.delivered or previous is not None and not previous.finished:
+                return None
+            call.claimed = True
+            return call
+
+    def finish(self, call_id):
+        with self.lock:
+            self.calls[call_id].finished = True
+
+    def cancel(self):
+        with self.lock:
+            self.cancelled = True

uni_robot_agent/agents/claude_code/sdk_compat.py

@@ -0,0 +1,27 @@
+"""Pinned SDK boundary for an MCP server with hook-only call identities.
+
+The public SDK helper validates arguments before invoking the tool callback.
+Hook metadata must be removed first, which requires the pinned low-level builder.
+"""
+from importlib.metadata import version
+
+
+def context_env():
+    """Disable the pinned CLI's synthetic token-budget reminders."""
+    return {"CLAUDE_CODE_TOTAL_TOKENS_REMINDER": "off"}
+
+
+def mcp_description_env(specs):
+    """Keep complete MCP descriptions in the pinned CLI's model requests."""
+    # The CLI defaults to 2048 JavaScript UTF-16 code units, not Python characters.
+    length = max((len(spec.get("description", "").encode("utf-16-le")) // 2
+                  for spec in specs), default=0)
+    return {"CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH": str(max(2048, length))}
+
+
+def build_tool_server(tools, callback):
+    installed = version("claude-agent-sdk")
+    if installed != "0.2.165":
+        raise RuntimeError(f"Claude MCP identity bridge requires claude-agent-sdk==0.2.165, got {installed}")
+    from claude_agent_sdk._internal._mcp_compat import build_tool_server as build
+    return build("uni_robot_agent", "1.0.0", tools, callback)