auto-coder 3.0.35__tar.gz → 3.0.36__tar.gz

{auto_coder-3.0.35/src/auto_coder.egg-info → auto_coder-3.0.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auto-coder
-Version: 3.0.35
+Version: 3.0.36
 Summary: AutoCoder: AutoCoder
 Author: allwefantasy
 Author-email: allwefantasy <allwefantasy@gmail.com>

{auto_coder-3.0.35 → auto_coder-3.0.36}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "auto-coder"
-version = "3.0.35"
+version = "3.0.36"
 description = "AutoCoder: AutoCoder"
 authors = [
     {name = "allwefantasy", email = "allwefantasy@gmail.com"}

{auto_coder-3.0.35 → auto_coder-3.0.36/src/auto_coder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auto-coder
-Version: 3.0.35
+Version: 3.0.36
 Summary: AutoCoder: AutoCoder
 Author: allwefantasy
 Author-email: allwefantasy <allwefantasy@gmail.com>

{auto_coder-3.0.35 → auto_coder-3.0.36}/src/auto_coder.egg-info/SOURCES.txt

@@ -545,6 +545,8 @@ src/autocoder/common/v2/agent/subagents/models.py
 src/autocoder/common/v2/agent/subagents/prompt_provider.py
 src/autocoder/common/v2/agent/subagents/backends/__init__.py
 src/autocoder/common/v2/agent/subagents/backends/cli_process.py
+src/autocoder/common/v2/agent/subagents/backends/external_cli_drivers.py
+src/autocoder/common/v2/agent/subagents/backends/external_cli_process.py
 src/autocoder/common/v2/agent/subagents/backends/in_process.py
 src/autocoder/common/v2/agent/subagents/tests/__init__.py
 src/autocoder/common/v2/agent/subagents/tests/test_subagent_client.py

{auto_coder-3.0.35 → auto_coder-3.0.36}/src/autocoder/common/v2/agent/agentic_edit.py

@@ -986,7 +986,7 @@ class AgenticEdit:
          </run_named_subagents>
 
          ## run_subagents
-         Description: Run subagents using the unified SubagentClient API. Supports in-process (default, faster, shares memory) and cli-process (isolated subprocess) backends. Use this tool for better performance and structured result handling.
+         Description: Run subagents using the unified SubagentClient API. Supports three backends: in-process (default, faster, shares memory), cli-process (isolated auto-coder.run subprocess), and external-cli-process (external CLI tools like Cursor CLI or Claude Code CLI). Each subagent runs in a completely isolated new session — no session sharing or resumption between subagents.
          Parameters:
          - subagents: (required) The subagents to run, in JSON or YAML format.
            - A JSON Array: [{"name": "agent_name", "task": "task description", "model": "optional_model"}]
@@ -1000,7 +1000,11 @@ class AgenticEdit:
              - name: (optional) A label for this subagent. If the name matches a pre-defined agent in .autocoderagents, its system prompt and model will be loaded automatically. Otherwise the subagent runs with the default system prompt.
              - task: (required) The task description for the subagent
              - model: (optional) Override the model for this specific subagent. If not specified, uses the model defined in the agent definition or the current model.
-         - backend: (optional) Execution backend. "in_process" (default, faster) or "cli_process" (isolated subprocess). Default is "in_process".
+         - backend: (optional) Execution backend. Default is "in_process".
+             - "in_process": fastest, shares memory with parent agent
+             - "cli_process": isolated auto-coder.run subprocess
+             - "external_cli_process": external CLI tool (requires external_cli parameter)
+         - external_cli: (optional) Which external CLI to use when backend is "external_cli_process". Must be "cursor" (Cursor CLI) or "claude_code" (Claude Code CLI). The external CLI tool must be installed and authenticated.
          - max_concurrency: (optional) Maximum number of subagents to run in parallel. Only applies when mode is "parallel". Default is no limit (all run concurrently).
          Usage:
          <run_subagents>
@@ -2167,7 +2171,7 @@ class AgenticEdit:
 
          ## Overview
 
-         When facing complex tasks that can be decomposed into independent subtasks, you can leverage the `run_subagents` tool to delegate work to sub-agents. Sub-agents run in-process by default (fast, shares memory) or as isolated CLI subprocesses. This allows you to delegate specific, isolated tasks to separate AI instances, significantly improving efficiency and task completion speed.
+         When facing complex tasks that can be decomposed into independent subtasks, you can leverage the `run_subagents` tool to delegate work to sub-agents. Sub-agents run in-process by default (fast, shares memory), as isolated auto-coder.run CLI subprocesses, or via external CLI tools (Cursor CLI / Claude Code CLI). Each subagent always runs in a completely isolated new session — no two subagents share context or conversation history. This allows you to delegate specific, isolated tasks to separate AI instances, significantly improving efficiency and task completion speed.
 
          ## When to Use Sub-Agents
 
@@ -2285,8 +2289,9 @@ class AgenticEdit:
 
          ### Backend Selection
 
-         - `in_process` (default): Faster, shares memory with the parent agent. Best for most tasks.
+         - `in_process` (default): Fastest, shares memory with the parent agent. Best for most tasks.
          - `cli_process`: Runs as isolated `auto-coder.run` subprocess. Use when full process isolation is required.
+         - `external_cli_process`: Runs via an external CLI tool. Set `external_cli` to `"cursor"` (Cursor CLI `agent` command) or `"claude_code"` (Claude Code CLI `claude` command). The external tool must be installed and authenticated by the user. Use when you want to leverage a different AI agent runtime.
 
          ### Task Delegation Strategy
          1. Analyze the main task to identify independent subtasks

{auto_coder-3.0.35 → auto_coder-3.0.36}/src/autocoder/common/v2/agent/agentic_edit_tools/execute_external_tool_resolver.py

@@ -492,8 +492,9 @@ class ExecuteExternalToolResolver(BaseToolResolver):
             else:
                 # 前台执行
                 timeout = self.tool.timeout
+                verbose = not get_run_context().is_terminal()
                 exit_code, output = execute_command(
-                    command, timeout=timeout, verbose=True, cwd=source_dir
+                    command, timeout=timeout, verbose=verbose, cwd=source_dir
                 )
 
                 logger.info(f"External tool executed: {masked_command}")

{auto_coder-3.0.35 → auto_coder-3.0.36}/src/autocoder/common/v2/agent/agentic_edit_tools/run_named_subagents_tool_resolver.py

@@ -337,8 +337,10 @@ class RunNamedSubagentsToolResolver(BaseToolResolver):
                 )
 
                 project_root = self.args.source_dir or "."
+                from autocoder.run_context import get_run_context
+                verbose = not get_run_context().is_terminal()
                 process_info = execute_command_background(
-                    command=argv, cwd=project_root, verbose=True
+                    command=argv, cwd=project_root, verbose=verbose
                 )
 
                 bg_proc: Dict[str, Any] = {

{auto_coder-3.0.35 → auto_coder-3.0.36}/src/autocoder/common/v2/agent/agentic_edit_tools/run_subagents_tool_resolver.py

@@ -1,8 +1,10 @@
 """
 Run Subagents Tool Resolver
 
-通过 SubagentClient 统一 API 执行子代理，支持 in_process / cli_process 后端切换
-和并发控制（max_concurrency）。
+通过 SubagentClient 统一 API 执行子代理，支持 in_process / cli_process /
+external_cli_process 后端切换和并发控制（max_concurrency）。
+
+每个 subagent 强制使用全新独立会话（share_mode=NEW），禁止任何会话共享或恢复。
 
 实现了 resolve_stream()，在子代理执行期间向 TUI 推送进度信息
 （ToolStreamEvent），避免长时间无反馈。
@@ -17,7 +19,6 @@ import yaml
 from loguru import logger
 
 from autocoder.common import AutoCoderArgs
-from autocoder.common.agents import AgentManager
 from autocoder.common.v2.agent.agentic_edit_tools.base_tool_resolver import (
     BaseToolResolver,
 )
@@ -41,9 +42,10 @@ class RunSubagentsToolResolver(BaseToolResolver):
 
     与 RunNamedSubagentsToolResolver 的区别：
     - 使用 SubagentClient 统一 API 而非 shell 命令拼接
-    - 支持 in_process（默认）和 cli_process 两种后端
+    - 支持 in_process（默认）、cli_process 和 external_cli_process 三种后端
     - 通过 max_concurrency 参数控制并行度
     - 返回结构化 SubagentResult
+    - 强制每个 subagent 使用全新独立会话（share_mode=NEW）
     """
 
     def __init__(
@@ -55,9 +57,6 @@ class RunSubagentsToolResolver(BaseToolResolver):
         super().__init__(agent, tool, args)
         self.tool: RunSubagentsTool = tool
 
-        project_root = args.source_dir if args.source_dir else "."
-        self.agent_manager = AgentManager(project_root)
-
     def resolve(self) -> ToolResult:
         from autocoder.common.v2.agent.agentic_edit_tools.run_named_subagents_tool_resolver import (
             _check_subagent_recursion,
@@ -216,7 +215,10 @@ class RunSubagentsToolResolver(BaseToolResolver):
             ]
             parallel = execution_mode == "parallel"
 
-            model_display = self.args.model or "unknown"
+            if backend_str == "external_cli_process":
+                model_display = "external CLI default"
+            else:
+                model_display = self.args.model or "unknown"
             yield f"Starting {total} sub-agents ({execution_mode} mode, backend={backend_str}, model={model_display})...\n"
             for i, name in enumerate(agent_names):
                 task_preview = subagents_list[i]["task"][:60]
@@ -314,11 +316,12 @@ class RunSubagentsToolResolver(BaseToolResolver):
         mapping = {
             "in_process": SubagentBackend.IN_PROCESS,
             "cli_process": SubagentBackend.CLI_PROCESS,
+            "external_cli_process": SubagentBackend.EXTERNAL_CLI_PROCESS,
         }
         if backend_str not in mapping:
             raise ValueError(
                 f"无效的 backend: '{backend_str}'，"
-                f"必须是 'in_process' 或 'cli_process'"
+                f"必须是 'in_process'、'cli_process' 或 'external_cli_process'"
             )
         return mapping[backend_str]
 
@@ -371,9 +374,9 @@ class RunSubagentsToolResolver(BaseToolResolver):
     ) -> Dict[str, Any]:
         """校验格式和必填字段。
 
-        注意：run_subagents 是通用工具，agent name 不要求在 .autocoderagents
-        中预定义。如果 name 对应的 agent 不存在，SubagentClient 会优雅降级
-        （不注入 system_prompt，使用默认提示词）。
+        注意：run_subagents 是通用工具，不会加载 .autocoderagents 中的 agent
+        定义。name 仅用于展示标签，不会触发 agent spec 查找或模型回填。
+        如需使用预定义 agent，请使用 run_named_subagents。
         """
         errors: List[str] = []
 
@@ -398,23 +401,41 @@ class RunSubagentsToolResolver(BaseToolResolver):
         subagents_list: List[Dict[str, str]],
         backend: "SubagentBackend",
     ) -> List["SubagentRequest"]:
-        from autocoder.common.v2.agent.subagents import SubagentRequest
+        from autocoder.common.v2.agent.subagents import (
+            ExternalCLIType,
+            SubagentBackend as _SubagentBackend,
+            SubagentRequest,
+            SubagentSessionOptions,
+            SubagentSessionShareMode,
+        )
 
         requests: List[SubagentRequest] = []
         timeout = self.args.call_subagent_timeout
+        tool_external_cli = self.tool.external_cli
 
         for entry in subagents_list:
             task = entry["task"]
             agent_name = entry.get("name") or None
             model = entry.get("model") or None
 
+            external_cli: Optional[ExternalCLIType] = None
+            if backend == _SubagentBackend.EXTERNAL_CLI_PROCESS:
+                external_cli_str = entry.get("external_cli") or tool_external_cli
+                if external_cli_str:
+                    external_cli = ExternalCLIType(external_cli_str)
+
             requests.append(
                 SubagentRequest(
                     task=task,
                     agent_name=agent_name,
                     backend=backend,
+                    external_cli=external_cli,
                     model=model,
                     timeout_seconds=int(timeout) if timeout else None,
+                    session=SubagentSessionOptions(
+                        share_mode=SubagentSessionShareMode.NEW,
+                    ),
+                    resolve_agent_spec=False,
                 )
             )
 

{auto_coder-3.0.35 → auto_coder-3.0.36}/src/autocoder/common/v2/agent/agentic_edit_types.py

@@ -161,11 +161,16 @@ class RunNamedSubagentsTool(BaseTool):
 class RunSubagentsTool(BaseTool):
     """
     Tool for running subagents via SubagentClient.
-    Supports in_process and cli_process backends with concurrency control.
+    Supports in_process, cli_process and external_cli_process backends
+    with concurrency control.
+
+    When backend="external_cli_process", external_cli must be set to
+    "cursor" or "claude_code" to select the external CLI tool.
     """
 
     subagents: str
     backend: Optional[str] = "in_process"
+    external_cli: Optional[str] = None
     max_concurrency: Optional[int] = None
 
 

{auto_coder-3.0.35 → auto_coder-3.0.36}/src/autocoder/common/v2/agent/subagents/__init__.py

@@ -19,6 +19,7 @@ Usage::
 from .client import SubagentClient
 from .models import (
     AgentPromptSpec,
+    ExternalCLIType,
     SubagentBackend,
     SubagentRequest,
     SubagentResult,
@@ -32,6 +33,7 @@ __all__ = [
     "SubagentRequest",
     "SubagentResult",
     "SubagentBackend",
+    "ExternalCLIType",
     "SubagentSessionShareMode",
     "SubagentSessionOptions",
     "AgentPromptSpec",

auto_coder-3.0.36/src/autocoder/common/v2/agent/subagents/backends/__init__.py

@@ -0,0 +1,5 @@
+from .in_process import InProcessBackend
+from .cli_process import CLIProcessBackend
+from .external_cli_process import ExternalCLIProcessBackend
+
+__all__ = ["InProcessBackend", "CLIProcessBackend", "ExternalCLIProcessBackend"]

auto_coder-3.0.36/src/autocoder/common/v2/agent/subagents/backends/external_cli_drivers.py

@@ -0,0 +1,172 @@
+"""
+外部 CLI 驱动器协议与实现。
+
+每种 Driver 负责：
+- 确定 CLI 命令名
+- 构建 argv（含 system_prompt 处理策略）
+- 确定子进程 cwd
+
+输出解析由 ExternalCLIProcessBackend 统一处理（Cursor / Claude Code 的
+stream-json NDJSON 格式一致）。
+
+model 策略：仅当 request.model 被显式指定时才传递 --model 给外部 CLI。
+不会回退到 args.code_model / args.model，因为那些是 auto-coder 内部的模型名
+（如 volcengine/coding/doubao-seed-2.0-pro），对外部 CLI 无意义。
+未指定 model 时让外部 CLI 使用自身默认模型。
+"""
+
+import shutil
+from typing import List, Optional, Protocol, Tuple
+
+from autocoder.common import AutoCoderArgs
+from autocoder.common.cli_invocation import get_command_path as _get_command_path
+
+from ..models import SubagentRequest
+
+
+class ExternalCLIDriver(Protocol):
+    """外部 CLI 工具驱动器协议。"""
+
+    @property
+    def cli_name(self) -> str: ...
+
+    def get_command(self) -> str:
+        """返回解析后的 CLI 可执行文件路径。"""
+        ...
+
+    def check_available(self) -> Optional[str]:
+        """检查 CLI 是否可用。返回 None 表示可用，否则返回错误信息。"""
+        ...
+
+    def build_argv(
+        self,
+        request: SubagentRequest,
+        args: AutoCoderArgs,
+        project_root: str,
+    ) -> Tuple[List[str], List[str]]:
+        """构建 argv 和 temp_files 列表。"""
+        ...
+
+    def get_cwd(self, project_root: str) -> str:
+        """返回子进程的工作目录。"""
+        ...
+
+
+class CursorCLIDriver:
+    """Cursor CLI (``agent``) 驱动器。
+
+    argv 模式::
+
+        agent -p --output-format stream-json --force
+              --workspace <project_root> --model <model>
+              <effective_task>
+
+    system_prompt 通过拼入 task 文本前部传递（Cursor CLI 不支持
+    --system-prompt-path 或 --append-system-prompt）。
+    """
+
+    @property
+    def cli_name(self) -> str:
+        return "cursor"
+
+    def get_command(self) -> str:
+        return _get_command_path("agent")
+
+    def check_available(self) -> Optional[str]:
+        if shutil.which("agent") is None:
+            return (
+                "Cursor CLI 命令 'agent' 未找到。"
+                "请先安装 Cursor CLI 并通过 'agent login' 完成认证，"
+                "或设置 CURSOR_API_KEY 环境变量。"
+            )
+        return None
+
+    def build_argv(
+        self,
+        request: SubagentRequest,
+        args: AutoCoderArgs,
+        project_root: str,
+    ) -> Tuple[List[str], List[str]]:
+        temp_files: List[str] = []
+        cmd = self.get_command()
+        argv = [cmd, "-p", "--output-format", "stream-json", "--force"]
+
+        argv.extend(["--workspace", project_root])
+
+        if request.model:
+            argv.extend(["--model", request.model])
+
+        effective_task = self._build_effective_task(request)
+        argv.append(effective_task)
+
+        return argv, temp_files
+
+    def get_cwd(self, project_root: str) -> str:
+        return project_root
+
+    @staticmethod
+    def _build_effective_task(request: SubagentRequest) -> str:
+        if request.system_prompt:
+            return (
+                f"<system_instructions>\n"
+                f"{request.system_prompt}\n"
+                f"</system_instructions>\n\n"
+                f"{request.task}"
+            )
+        return request.task
+
+
+class ClaudeCodeCLIDriver:
+    """Claude Code CLI (``claude``) 驱动器。
+
+    argv 模式::
+
+        claude -p --output-format stream-json
+               --allowedTools "Bash,Read,Edit,Write"
+               --model <model>
+               [--append-system-prompt <prompt>]
+               <task>
+
+    system_prompt 通过 ``--append-system-prompt`` 直接传递。
+    cwd 设为 project_root（Claude Code 通过工作目录确定项目范围）。
+    """
+
+    @property
+    def cli_name(self) -> str:
+        return "claude_code"
+
+    def get_command(self) -> str:
+        return _get_command_path("claude")
+
+    def check_available(self) -> Optional[str]:
+        if shutil.which("claude") is None:
+            return (
+                "Claude Code CLI 命令 'claude' 未找到。"
+                "请先安装 Claude Code CLI 并设置 ANTHROPIC_API_KEY 环境变量。"
+            )
+        return None
+
+    def build_argv(
+        self,
+        request: SubagentRequest,
+        args: AutoCoderArgs,
+        project_root: str,
+    ) -> Tuple[List[str], List[str]]:
+        temp_files: List[str] = []
+        cmd = self.get_command()
+        argv = [cmd, "-p", "--output-format", "stream-json"]
+
+        argv.extend(["--allowedTools", "Bash,Read,Edit,Write"])
+
+        if request.model:
+            argv.extend(["--model", request.model])
+
+        if request.system_prompt:
+            argv.extend(["--append-system-prompt", request.system_prompt])
+
+        argv.append(request.task)
+
+        return argv, temp_files
+
+    def get_cwd(self, project_root: str) -> str:
+        return project_root

auto_coder-3.0.36/src/autocoder/common/v2/agent/subagents/backends/external_cli_process.py

@@ -0,0 +1,211 @@
+"""
+外部 CLI 后端：通过 Cursor CLI / Claude Code CLI 等外部工具执行子代理。
+
+使用 --output-format stream-json 获取 NDJSON 事件流，两种 CLI 的输出格式
+高度一致（type/subtype/session_id/result），由 _parse_output 统一解析。
+
+会话约束：EXTERNAL_CLI_PROCESS 后端仅支持 share_mode=NEW（全新会话），
+不支持 COPY_PARENT / RESUME_PARENT / RESUME。如果请求中包含非 NEW 的
+share_mode，将直接报错。
+"""
+
+import json
+import os
+import subprocess
+from typing import Any, Dict, List, Optional, Tuple
+
+from loguru import logger
+
+from autocoder.common import AutoCoderArgs
+from autocoder.common.global_cancel import global_cancel
+from autocoder.common.shell_commands import execute_command
+
+from ..models import (
+    ExternalCLIType,
+    SubagentBackend,
+    SubagentRequest,
+    SubagentResult,
+    SubagentSessionShareMode,
+)
+from .external_cli_drivers import (
+    ClaudeCodeCLIDriver,
+    CursorCLIDriver,
+    ExternalCLIDriver,
+)
+
+
+class ExternalCLIProcessBackend:
+    """外部 CLI 后端：通过 Cursor CLI / Claude Code CLI 执行子代理。"""
+
+    def __init__(
+        self, args: AutoCoderArgs, project_root: str, driver: ExternalCLIDriver
+    ) -> None:
+        self._args = args
+        self._project_root = project_root
+        self._driver = driver
+
+    @staticmethod
+    def get_driver(external_cli: Optional[ExternalCLIType]) -> ExternalCLIDriver:
+        """根据 ExternalCLIType 返回对应的 Driver 实例。"""
+        if external_cli is None:
+            raise ValueError(
+                "EXTERNAL_CLI_PROCESS 后端必须指定 external_cli 参数 "
+                "('cursor' 或 'claude_code')"
+            )
+        if external_cli == ExternalCLIType.CURSOR:
+            return CursorCLIDriver()
+        if external_cli == ExternalCLIType.CLAUDE_CODE:
+            return ClaudeCodeCLIDriver()
+        raise ValueError(f"不支持的 external_cli 类型: {external_cli}")
+
+    def run(self, request: SubagentRequest) -> SubagentResult:
+        cli_name = self._driver.cli_name
+        temp_files: List[str] = []
+        try:
+            self._validate_session(request)
+
+            available_err = self._driver.check_available()
+            if available_err is not None:
+                logger.warning(
+                    f"ExternalCLIProcessBackend[{cli_name}]: "
+                    f"CLI not available: {available_err}"
+                )
+                return SubagentResult(
+                    success=False,
+                    backend=SubagentBackend.EXTERNAL_CLI_PROCESS,
+                    error=available_err,
+                )
+
+            argv, new_temps = self._driver.build_argv(
+                request, self._args, self._project_root
+            )
+            temp_files.extend(new_temps)
+            cwd = self._driver.get_cwd(self._project_root)
+
+            logger.info(
+                f"ExternalCLIProcessBackend[{cli_name}]: "
+                f"launching subagent (agent_name={request.agent_name}, "
+                f"model={request.model}, cwd={cwd})"
+            )
+            logger.info(
+                f"ExternalCLIProcessBackend[{cli_name}]: "
+                f"argv={argv[:4]}... (task_len={len(request.task)})"
+            )
+
+            timeout = request.timeout_seconds
+            if timeout is None:
+                timeout = self._args.call_subagent_timeout
+
+            cancel_token = request.cancel_token
+            if cancel_token and global_cancel.is_requested(cancel_token):
+                return SubagentResult(
+                    success=False,
+                    backend=SubagentBackend.EXTERNAL_CLI_PROCESS,
+                    error="cancelled before execution",
+                )
+
+            exit_code, output = execute_command(
+                command=argv,
+                timeout=timeout,
+                cwd=cwd,
+                stdin=subprocess.DEVNULL,
+            )
+
+            logger.info(
+                f"ExternalCLIProcessBackend[{cli_name}]: "
+                f"process finished (exit_code={exit_code}, "
+                f"output_len={len(output)})"
+            )
+
+            if exit_code != 0:
+                output_preview = output[:500] if output else "(empty)"
+                logger.warning(
+                    f"ExternalCLIProcessBackend[{cli_name}]: "
+                    f"non-zero exit code {exit_code}, "
+                    f"output preview: {output_preview}"
+                )
+
+            session_id, result_text, events = self._parse_output(
+                output, request.collect_events
+            )
+
+            success = exit_code == 0 and result_text is not None
+            error_msg = None
+            if not success:
+                output_preview = output[:300] if output else "(empty)"
+                error_msg = (
+                    f"exit_code={exit_code}, output_preview={output_preview}"
+                )
+
+            return SubagentResult(
+                success=success,
+                backend=SubagentBackend.EXTERNAL_CLI_PROCESS,
+                conversation_id=session_id,
+                attempt_result=result_text,
+                error=error_msg,
+                events=events,
+            )
+        except Exception:
+            logger.exception(
+                f"ExternalCLIProcessBackend[{cli_name}] error"
+            )
+            import traceback
+
+            return SubagentResult(
+                success=False,
+                backend=SubagentBackend.EXTERNAL_CLI_PROCESS,
+                error=traceback.format_exc(),
+            )
+        finally:
+            for f in temp_files:
+                try:
+                    os.unlink(f)
+                except OSError:
+                    pass
+
+    @staticmethod
+    def _validate_session(request: SubagentRequest) -> None:
+        """确保外部 CLI 后端只接受 NEW 会话模式。"""
+        share_mode = request.session.share_mode
+        if share_mode != SubagentSessionShareMode.NEW:
+            raise ValueError(
+                f"EXTERNAL_CLI_PROCESS 后端不支持 share_mode={share_mode.value}，"
+                f"仅支持 share_mode=NEW（全新会话）。"
+            )
+
+    @staticmethod
+    def _parse_output(
+        output: str,
+        collect_events: bool,
+    ) -> Tuple[Optional[str], Optional[str], Optional[List[Dict[str, Any]]]]:
+        """解析外部 CLI 的 stream-json NDJSON 输出。
+
+        Cursor CLI 和 Claude Code CLI 的事件格式一致：
+        - init: {"type":"system","subtype":"init","session_id":"..."}
+        - result: {"type":"result","subtype":"success","result":"..."}
+        """
+        session_id: Optional[str] = None
+        result_text: Optional[str] = None
+        events: Optional[List[Dict[str, Any]]] = [] if collect_events else None
+
+        for line in output.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            event_type = obj.get("type", "")
+            subtype = obj.get("subtype", "")
+
+            if event_type == "system" and subtype == "init":
+                session_id = obj.get("session_id")
+            elif event_type == "result" and subtype == "success":
+                result_text = obj.get("result")
+
+            if events is not None:
+                events.append(obj)
+
+        return session_id, result_text, events