@scemoon/cdh 1.0.4 → 1.0.6

package/onecode/agent/engine.py

@@ -1,15 +1,16 @@
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import re
-import time
 from pathlib import Path
-from typing import AsyncIterator, Optional
+from typing import Any, AsyncIterator, Optional
 
 from dataclasses import dataclass
 from typing import Callable
 
+from onecode.agent.agents.types import AgentPermission
 from onecode.agent.context import ContextManager
 from onecode.agent.permissions_store import PermissionStore
 from onecode.models.provider import ContentBlockType, ProviderRegistry
@@ -39,6 +40,11 @@ class ToolEvent:
 
 ToolEventHandler = Callable[[ToolEvent], None]
 
+
+class TurnCancelledError(Exception):
+    """Raised when the user cancels the agent's turn mid-execution."""
+
+
 TOOL_CALL_RE = re.compile(
     r'<tool_call\s+name=["\']([^"\']+)["\']\s+id=["\']([^"\']+)["\']>(.*?)</tool_call>',
     re.DOTALL,
@@ -390,6 +396,7 @@ class TodoManager:
     def clear_todos(self) -> None:
         self._todos.clear()
         self._order.clear()
+        self._id_counter = 0
         self._mark_dirty()
 
     # ── Serialization ──
@@ -411,7 +418,22 @@ class TodoManager:
         on the fly to the new ``{subject, status}`` shape.
         """
         tm = cls(on_change=on_change)
-        tm._id_counter = data.get("id_counter", 0)
+        tm.reload_from_dict(data)
+        return tm
+
+    def reload_from_dict(self, data: dict) -> None:
+        """Reload state from *data* in place, preserving the instance identity.
+
+        This is critical because tool instances (``TodoCreateTool`` etc.)
+        hold a direct reference to the same ``TodoManager`` object.  If we
+        replaced ``self._todo_manager`` with a new instance, the tools
+        would silently write to the stale one while the engine reads from
+        the fresh one — creating the illusion of success but never
+        persisting or emitting plan updates.
+        """
+        self._todos.clear()
+        self._order.clear()
+        self._id_counter = data.get("id_counter", 0)
 
         raw_todos: list[dict] = []
         if "todos" in data:
@@ -426,13 +448,12 @@ class TodoManager:
             if "status" not in todo and "done" in todo:
                 todo["status"] = "completed" if todo.pop("done") else "pending"
             todo.setdefault("status", "pending")
-            tid = todo.get("id") or tm._next_id()
+            tid = todo.get("id") or self._next_id()
             todo["id"] = tid
-            todo.setdefault("_order", tm._id_counter)
-            tm._todos[tid] = todo
-            if tid not in tm._order:
-                tm._order.append(tid)
-        return tm
+            todo.setdefault("_order", self._id_counter)
+            self._todos[tid] = todo
+            if tid not in self._order:
+                self._order.append(tid)
 
 
 # Tools that require a task plan before execution (plan gate)
@@ -457,7 +478,7 @@ class AgentEngine:
         self.context = ContextManager()
         self.file_ops = ToolFactory.create_file_ops(self._project_dir)
         self.shell = ToolFactory.create_shell(self._project_dir)
-        self.current_agent: AgentConfig = BuildAgent()
+        self.current_agent: AgentConfig = BuildAgent()  # noqa: F821
         self.iterations = 0
         self.total_tokens = 0
         self._skills_loaded = False
@@ -486,7 +507,7 @@ class AgentEngine:
         self._config_tool_write = ConfigWriteTool(app_config) if app_config else None
 
         # Codebase engine (lazy init)
-        self._codebase_engine: Optional["CodebaseEngine"] = None
+        self._codebase_engine: Optional["CodebaseEngine"] = None  # noqa: F821
 
         # Tool registry (Clawd-Code pattern)
         self._tool_registry = self._build_tool_registry()
@@ -509,6 +530,19 @@ class AgentEngine:
         # Subagent depth limit — subagents are leaf nodes (max depth = 1).
         self._subagent_depth: int = 0
 
+        # Skip codebase auto-retrieval / long-term memory recall inside
+        # subagent engines.  Both are project-seeding steps meant for the
+        # top-level chat loop; a subagent already receives a fully-formed
+        # explicit prompt from the parent and does NOT need toEmbed/index
+        # the whole codebase or recall memories again — that path
+        # previously called ``CodebaseIndexer.index()`` (a long
+        # synchronous loop, blocking the event loop and cancel) plus
+        # ``CodebaseRetriever._retrieve_embedding()`` (one httpx call per
+        # chunk, each with a 30s timeout, so ~minutes of dead time), which
+        # is the root cause of the "subagent shows no stream output and
+        # can't be stopped" hang observed in production.
+        self._disable_retrieval: bool = False
+
         # Monotonic tool-call id counter — shared across every
         # ``chat_stream`` turn so the same id is never reused even when the
         # model re-emits ``legacy-0`` / ``minimax-0`` in a fresh turn.
@@ -535,7 +569,12 @@ class AgentEngine:
         self._react_phase: str = "thought"  # "thought" | "action" | "observation"
         self._direct_execution_count: int = 0  # Track direct tool use for routing-decision reminder
 
-    def _build_tool_registry(self) -> ToolRegistry:
+        # Consecutive turns with zero tool_uses — if the LLM repeatedly
+        # refuses to call tools despite pending todos, we cap the loop
+        # instead of cycling until max_turns is exhausted.
+        self._empty_tool_turns: int = 0
+
+    def _build_tool_registry(self) -> ToolRegistry:  # noqa: F821
         from onecode.agent.tools.registry import ToolRegistry
         from onecode.agent.tools.file_tools import ReadTool, WriteTool, EditTool, InsertTool, UndoEditTool, GlobTool, GrepTool, ListTool
         from onecode.agent.tools.apply_patch_tool import ApplyPatchTool
@@ -543,7 +582,7 @@ class AgentEngine:
         from onecode.agent.tools.web_tools import WebFetchTool, WebSearchTool
         from onecode.agent.tools.communication_tools import SendMessageTool, AskUserTool, ToolSearchTool
         from onecode.agent.tools.todo_tools import (TodoCreateTool, TodoGetTool, TodoListTool, TodoUpdateTool,
-            TodoOutputTool, TodoStopTool)
+            TodoOutputTool, TodoStopTool, TodoClearTool)
         from onecode.agent.tools.agent_tools import AgentTool, TaskTool
         from onecode.agent.tools.skill_tools import SkillTool
         from onecode.agent.tools.mcp_tools import MCPTool as MCPToolTool, MCPResourcesTool
@@ -577,6 +616,7 @@ class AgentEngine:
         registry.register(TodoUpdateTool(self._todo_manager))
         registry.register(TodoOutputTool(self._todo_manager))
         registry.register(TodoStopTool(self._todo_manager))
+        registry.register(TodoClearTool(self._todo_manager))
         # Agent tools
         registry.register(AgentTool(registry, permission_checker=self._check_tool_permission))
         registry.register(TaskTool(self._spawn_subagent_async))
@@ -684,23 +724,96 @@ class AgentEngine:
         ]
         return [StreamEvent.plan(wire_entries)]
 
+    def _has_pending_todos(self) -> bool:
+        """Return True if there are any pending or in-progress todos."""
+        return any(
+            t.get("status") in ("pending", "in_progress")
+            for t in self._todo_manager.list_todos()
+        )
+
+    def _build_completion_summary(self) -> str:
+        """Build a deterministic completion summary from todo state.
+
+        Called after the agent loop exits when the last round had no
+        visible text — ensures the user always sees a completion report
+        without an extra LLM round-trip.
+        """
+        todos = self._todo_manager.list_todos()
+        completed = [t for t in todos if t.get("status") == "completed"]
+        failed = [t for t in todos if t.get("status") == "failed"]
+        pending = [t for t in todos if t.get("status") in ("pending", "in_progress")]
+
+        lines = ["\n---", "## Session Complete", ""]
+
+        if not todos:
+            lines.append("No todos were tracked in this session.")
+        else:
+            if completed:
+                lines.append(f"**Completed** ({len(completed)}):")
+                for t in completed:
+                    lines.append(f"- {t.get('subject') or t.get('description', '')}")
+                lines.append("")
+            if pending:
+                lines.append(f"**Unfinished** ({len(pending)}):")
+                for t in pending:
+                    lines.append(f"- {t.get('subject') or t.get('description', '')}")
+                lines.append("")
+            if failed:
+                lines.append(f"**Failed** ({len(failed)}):")
+                for t in failed:
+                    lines.append(f"- {t.get('subject') or t.get('description', '')}")
+                lines.append("")
+
+        lines.append(
+            f"**Stats**: {self.iterations} round(s), "
+            f"{self.total_tokens} tokens"
+        )
+        return "\n".join(lines)
+
+    def _auto_advance_after_spawn(self, subagent_prompt: str) -> None:
+        """After a Spawn subagent completes, auto-advance todo status.
+
+        Finds the first ``in_progress`` todo (typically the one the subagent
+        was working on) and marks it ``completed``.  If another ``pending``
+        todo remains, injects a user message into the LLM context directing
+        the agent to continue — no need to wait for the LLM to spontaneously
+        call ``TodoUpdate`` then ``Spawn`` again.
+        """
+        todos = self._todo_manager.list_todos()
+        in_progress = [t for t in todos if t.get("status") == "in_progress"]
+        if in_progress:
+            tid = in_progress[0]["id"]
+            self._todo_manager.update_todo(tid, status="completed")
+
+        pending = [t for t in self._todo_manager.list_todos() if t.get("status") == "pending"]
+        if pending:
+            lines = ["# Continue working — remaining todos", ""]
+            for t in pending:
+                sub = t.get("subject", "")
+                desc = t.get("description", "")
+                if desc and desc != sub:
+                    lines.append(f"- `{t['id']}`: {sub} — {desc}")
+                else:
+                    lines.append(f"- `{t['id']}`: {sub}")
+            lines.append("")
+            lines.append("Continue with the next pending todo above. Do NOT stop.")
+            body = "\n".join(lines)
+            self.context.add_message("user", [{"type": "text", "text": body}])
+
     def _refresh_pending_todos_nudge(self) -> None:
         """Inject a reminder that nudges the agent to advance unfinished todos.
 
         Called at the start of each ReAct turn. If there are pending or
-        in-progress todos, a ``<!-- PENDING_TODOS -->`` section is added to
-        the system context so the LLM sees it during its next Thought phase
-        and prefers to:
-          1. continue the in-progress todo, or
-          2. start the next pending todo (respecting ``addBlockedBy`` DAG), or
-          3. call ``AskUser`` if the todo is blocked on user input.
+        in-progress todos, a strong ``<!-- PENDING_TODOS -->`` section is
+        injected into the system context directing the agent to continue
+        working rather than summarising or stopping early.
 
         When no todos are open, any stale nudge is removed so the context
         stays clean.
         """
         marker = "<!-- PENDING_TODOS -->"
-        todos = self._todo_manager.list_todos()
-        open_todos = [t for t in todos if t.get("status") in ("pending", "in_progress")]
+        open_todos = [t for t in self._todo_manager.list_todos()
+                      if t.get("status") in ("pending", "in_progress")]
         if not open_todos:
             self.context.remove_system_by_marker(marker)
             return
@@ -716,26 +829,19 @@ class AgentEngine:
             return f"- `{sid}`{owner_part}: {sub}"
 
         lines: list[str] = []
-        lines.append(
-            "There are unfinished todos from earlier in this session. Prioritize "
-            "them before starting new work: finish in-progress items, then move "
-            "to the next pending todo in DAG order (respect `addBlockedBy`). "
-            "If a todo is blocked on user input or external information, call "
-            "`AskUser` to clarify instead of starting a new branch."
-        )
+        total = len(in_progress) + len(pending)
+        lines.append(f"## ⚠️ Open todos ({total}) — you MUST continue working on these")
+        lines.append("Do NOT end your turn until ALL todos below are completed.")
         if in_progress:
-            lines.append("")
-            lines.append("**In progress:**")
-            lines.extend(_label(t) for t in in_progress)
+            labels = "\n".join(_label(t) for t in in_progress)
+            lines.append(f"\nIn progress:\n{labels}")
         if pending:
-            lines.append("")
-            lines.append("**Pending:**")
-            lines.extend(_label(t) for t in pending)
-        lines.append("")
+            labels = "\n".join(_label(t) for t in pending)
+            lines.append(f"\nPending:\n{labels}")
         lines.append(
-            "Next action: either `TodoUpdate(status=\"in_progress\")` to pick one "
-            "up, advance it with the appropriate tool, and `TodoUpdate(status=\"completed\")` "
-            "when done — or `AskUser` to unblock."
+            "\nFor each completed todo, call TodoUpdate(status=\"completed\") "
+            "immediately. Then proceed to the next pending todo. "
+            "Do NOT summarise or stop — keep working."
         )
         body = f"{marker}\n" + "\n".join(lines)
         if not self.context.replace_system_section(marker, body):
@@ -746,8 +852,12 @@ class AgentEngine:
 
         Sets a dirty flag so the next opportunity in ``chat_stream`` will
         emit a fresh plan event.  Decoupling the callback from the emit
-        keeps the public API synchronous and avoids re-entrancy when
-        subagents mutate the same TodoManager concurrently.
+        keeps the public API synchronous and avoids re-entrancy.
+
+        Subagents have an isolated TodoManager and (since Todo tools are
+        denied via disallowed_tools for subagents) cannot mutate the parent's
+        shared plan, so this callback only fires for the main agent's own
+        TodoManager.
 
         Also persists todos to ``.cdh/todos.json`` immediately so they
         survive a crash or Ctrl+C before the next ACP turn boundary.
@@ -761,11 +871,13 @@ class AgentEngine:
 
     def set_agent(self, agent_type: str) -> None:
         from onecode.agent.agents.types import (
+            AgentMode,
             AgentPermission,
+            SUBAGENT_CONSTRAINTS,
             create_agent,
-            PLAN_INSTRUCTIONS,
-            REACT_CYCLE,
-            TOOL_DESCRIPTIONS,
+            PLAN_GATE_HARD,
+            PLAN_GATE_SOFT,
+            REACT_WORKFLOW,
             filter_tool_descriptions,
         )
         self.current_agent = create_agent(agent_type)
@@ -781,51 +893,97 @@ class AgentEngine:
                 restrictions.append("- Shell commands require user approval")
             system_parts.append("\n".join(restrictions))
 
+        if self.current_agent.mode == AgentMode.SUBAGENT:
+            system_parts.append(SUBAGENT_CONSTRAINTS)
+
         if self.current_agent.permission_task != AgentPermission.DENY:
-            system_parts.append(REACT_CYCLE)
-            system_parts.append(PLAN_INSTRUCTIONS)
-
-        # Tell the model how to format intermediate reasoning so the TUI
-        # can render it as a collapsible "thought" block instead of
-        # leaking it into the visible answer.  Without these tags, the
-        # model's planning prose ("I will now update X…", "X is done,
-        # let me verify…") flows through as plain ``agent_message_chunk``
-        # and shows up in chat interleaved with tool calls.
-        system_parts.append(
-            "\n## Response style\n"
-            "- **Every turn must start with Chain of Thought reasoning** "
-            "inside `<thinking>`. Analyze the current state, determine the "
-            "next step, and decide whether to delegate via `Spawn` or track via `TodoCreate`.\n"
-            "- **Route by complexity**:\n"
-            "  - Simple / single-step work → use the direct tool and optionally "
-            "`TodoCreate` to surface progress in the sidebar.\n"
-            "  - Complex / multi-step work → use `Spawn(agent_type, prompt)` to "
-            "delegate to a focused subagent rather than calling execution tools directly.\n"
-            "- If you need to reason between tool calls, wrap your "
-            "reasoning in `<thinking>...</thinking>`.  The TUI will "
-            "render the wrapped block as a collapsible thought and "
-            "keep it out of the main answer.\n"
-            "- Do not narrate your plan in the visible answer.  Avoid "
-            'phrases like "I will now…", "Let me first…", "X is done, '
-            'let me verify…" — those should go inside `<thinking>`.  '
-            "The visible answer is only the final user-facing summary.\n"
-        )
+            system_parts.append(REACT_WORKFLOW)
+            if self.current_agent.mode.name == "SUBAGENT":
+                pass  # subagents don't need plan gate
+            elif self.current_agent.permission_edit == AgentPermission.DENY and self.current_agent.permission_bash == AgentPermission.DENY:
+                pass  # read-only mode, no gate needed
+            elif self.current_agent.permission_task == AgentPermission.DENY:
+                pass
+            else:
+                gate = PLAN_GATE_HARD if self.current_agent.mode == AgentMode.PRIMARY and self.current_agent.name == "plan" else PLAN_GATE_SOFT
+                system_parts.append(gate)
+
+        # Response style with CoT reasoning guidance.
+        if self.current_agent.mode == AgentMode.SUBAGENT:
+            # Subagents: simple CoT guidance without Todo/Spawn instructions.
+            system_parts.append(
+                "\n## Response style\n"
+                "- **Every round must start with Chain of Thought reasoning** "
+                "inside `<thinking>`. Review the last round's tool results, "
+                "assess progress, and decide the next action.\n"
+                "- If you need to reason between tool calls, wrap your "
+                "reasoning in `<thinking>...</thinking>`.  The TUI will "
+                "render the wrapped block as a collapsible thought and "
+                "keep it out of the main answer.\n"
+                "- **Intermediate rounds**: visible text is for progress "
+                "updates, status reports, and questions.  Do NOT announce "
+                '"done" or "complete" unless ALL work is actually finished.\n'
+                "- **FINAL round** (all work done): output a visible summary "
+                "describing what was accomplished, changed, or decided.\n"
+            )
+        else:
+            system_parts.append(
+                "\n## Response style\n"
+                "- **Every round must start with Chain of Thought reasoning** "
+                "inside `<thinking>`. Review the last round's tool results, "
+                "assess progress against todos, and decide the next action. "
+                "Then plan with `TodoCreate` and route execution by complexity.\n"
+                "- **Plan + execution routing**:\n"
+                "  - Every task is a `TodoCreate` (persisted to .cdh/todos.json, "
+                "sidebar Plan). No work without a todo.\n"
+                "  - Simple / single-step todo → execute directly, then "
+                "`TodoUpdate(status=\"completed\")`.\n"
+                "  - Complex / multi-step todo → `Spawn(agent_type, prompt)` to "
+                "delegate execution to an isolated subagent, then "
+                "`TodoUpdate(status=\"completed\")`.\n"
+                "  - Use `TodoClear` to reset the entire plan and start fresh.\n"
+                "- If you need to reason between tool calls, wrap your "
+                "reasoning in `<thinking>...</thinking>`.  The TUI will "
+                "render the wrapped block as a collapsible thought and "
+                "keep it out of the main answer.\n"
+                "- **Intermediate rounds**: visible text is for progress "
+                "updates, status reports, and user questions.  Do NOT "
+                'announce "done", "complete", or "task finished" unless '
+                "ALL todos are actually completed.\n"
+                "- Do NOT call `TodoUpdate(status=\"completed\")` unless you "
+                "have actually executed the work (tool calls or Spawn).\n"
+                "- **FINAL round** (all todos completed, all work done): "
+                "output a visible summary describing what was accomplished, "
+                "what was changed, and any important outcomes or limitations.\n"
+            )
+
+        tagged_content = "<!-- AGENT_CONFIG -->\n" + "\n".join(system_parts)
+        if not self.context.replace_system_section("AGENT_CONFIG", tagged_content):
+            self.context.add_system(tagged_content)
 
+        # Inject TOOL_DESCRIPTIONS as its own marker so it can be independently
+        # stripped when the provider supports native tool schemas.
         tool_desc = filter_tool_descriptions(
             allowlist=self.current_agent.tools or None,
             denylist=self.current_agent.disallowed_tools or None,
         )
-        system_parts.append(tool_desc)
-
-        tagged_content = "<!-- AGENT_CONFIG -->\n" + "\n".join(system_parts)
-        if not self.context.replace_system_section("AGENT_CONFIG", tagged_content):
-            self.context.add_system(tagged_content)
+        tool_tagged = "<!-- TOOL_DESCRIPTIONS -->\n" + tool_desc
+        if not self.context.replace_system_section("TOOL_DESCRIPTIONS", tool_tagged):
+            self.context.add_system(tool_tagged)
 
         # Re-apply user permission overrides (e.g. "allow always")
         self._perm_store.apply_to(self.current_agent)
 
+    def _strip_agent_config_tool_descriptions(self) -> None:
+        """Remove the ``<!-- TOOL_DESCRIPTIONS -->`` system section.
+
+        Called after the provider is known, for providers that support
+        native tool schemas and don't need the prose TOOL_DESCRIPTIONS.
+        """
+        self.context.remove_system_by_marker("<!-- TOOL_DESCRIPTIONS -->")
+
     def get_available_tools(self) -> str:
-        from onecode.agent.agents.types import TOOL_DESCRIPTIONS, filter_tool_descriptions
+        from onecode.agent.agents.types import filter_tool_descriptions
         return filter_tool_descriptions(
             allowlist=self.current_agent.tools or None,
             denylist=self.current_agent.disallowed_tools or None,
@@ -838,6 +996,7 @@ class AgentEngine:
         # Remove previously loaded skill-tagged messages so they don't
         # accumulate across agent switches or skill re-loads.
         self.context.remove_system_by_marker("<!-- SKILL:")
+        self.context.remove_system_by_marker("<!-- PROJECT_DOC -->")
         self.context.remove_system_by_marker("<!-- CDH_PROJECT -->")
         self._skills_loaded = True
 
@@ -845,6 +1004,12 @@ class AgentEngine:
             tagged = f"<!-- SKILL:{skill.name} -->\n{skill.content}"
             self.context.add_system(tagged)
 
+        # Project-level single-file doc (AGENTS.md at workspace root)
+        from onecode.agent.project_doc import load_project_doc
+        project_doc = load_project_doc(self._workspace)
+        if project_doc:
+            self.context.add_system(f"<!-- PROJECT_DOC -->\n{project_doc}")
+
         # Load project .cdh/ state into context
         from onecode.agent.cdh_loader import CdhProjectLoader
         cdh_content = CdhProjectLoader.load_for_workspace(self._workspace)
@@ -869,14 +1034,6 @@ class AgentEngine:
         if env_id:
             context_parts.append(f"TCB EnvId: {env_id}")
 
-        agents_md_path = self._workspace / "AGENTS.md"
-        if agents_md_path.exists():
-            try:
-                content = agents_md_path.read_text(encoding="utf-8")
-                context_parts.append(f"\n--- AGENTS.md ---\n{content[:2000]}")
-            except Exception:
-                pass
-
         self.context.add_system("\n".join(context_parts))
 
     def _should_retrieve_codebase(self) -> bool:
@@ -982,11 +1139,26 @@ class AgentEngine:
         "Spawn": "task",
         "Agent": "task",
         "Skill": "skill",
+        "codebase_search": "read",
+        "TodoCreate": "todowrite",
+        "TodoGet": "todowrite",
+        "TodoList": "todowrite",
+        "TodoUpdate": "todowrite",
+        "TodoOutput": "todowrite",
+        "TodoStop": "todowrite",
+        "TodoClear": "todowrite",
     }
 
     def _check_tool_permission(self, name: str, inp: dict) -> str | None:
         """Unified agent-level permission check for all tools."""
         from onecode.agent.agents.types import AgentPermission
+        # Enforce agent allow/deny lists at runtime. This is the runtime
+        # safety net behind filter_tool_descriptions(): even if the LLM
+        # still emits a tool the system prompt hid (e.g. TodoCreate in a
+        # subagent, after context compaction re-introduced the name), the
+        # call is denied here rather than leaking through.
+        if not self.current_agent.tool_allowed(name):
+            return json.dumps({"success": False, "error": f"{name} denied (disallowed for {self.current_agent.name})"})
         perm_key = self._TOOL_NAME_TO_PERM_KEY.get(name)
         if perm_key is None:
             return None
@@ -1011,7 +1183,9 @@ class AgentEngine:
                 return {**base, "content": denied, "is_error": True}
 
             call = RegistryToolCall(name=name, input=inp, tool_use_id=tid)
-            result = self._tool_registry.dispatch(call)
+            result = await self._tool_registry.dispatch_async(
+                call, cancel_check=lambda: self._cancelled,
+            )
 
             # Handle SendMessage tracking
             if name == "SendMessage":
@@ -1026,7 +1200,7 @@ class AgentEngine:
             logger.exception(f"Tool execution error: {e}")
             return {**base, "content": f"Error: {safe_error_msg(e)}", "is_error": True}
 
-    def _format_tool_output(self, result: RegistryToolResult) -> str:
+    def _format_tool_output(self, result: RegistryToolResult) -> str:  # noqa: F821
         import json
         output = result.output
         if isinstance(output, str):
@@ -1042,6 +1216,20 @@ class AgentEngine:
         for child in self._child_engines:
             child._cancelled = True
 
+    async def shutdown(self):
+        """Release OS resources held by this engine (LSP, MCP, cron)."""
+        self._cancelled = True
+        for child in self._child_engines:
+            child._cancelled = True
+        self._lsp_tool.stop_all()
+        await self._mcp.disconnect_all()
+        self._cron_scheduler.stop_loop()
+
+    def __del__(self):
+        """Fallback cleanup on garbage collection."""
+        self._lsp_tool.stop_all()
+        self._cron_scheduler.stop_loop()
+
     async def chat_stream(self, user_input: str | list[dict]) -> AsyncIterator[StreamEvent | str]:
         self._load_skills()
         preview = user_input[:100] if isinstance(user_input, str) else f"[{len(user_input)} content blocks]"
@@ -1068,7 +1256,14 @@ class AgentEngine:
         self._plan_dirty = False
 
         # ── Codebase auto-retrieval ──
-        if isinstance(user_input, str) and self._should_retrieve_codebase():
+        # Skipped entirely for subagent engines (see _disable_retrieval)
+        # to avoid the 2.3s+ indexer loop and the per-chunk embedding httpx
+        # calls that block the event loop and freeze streaming/cancel.
+        if (
+            isinstance(user_input, str)
+            and self._should_retrieve_codebase()
+            and not self._disable_retrieval
+        ):
             try:
                 engine = await self._get_codebase_engine()
                 if engine:
@@ -1083,9 +1278,16 @@ class AgentEngine:
                 logger.warning("Codebase retrieval failed: %s", e)
 
         # ── Long-term memory recall ──
-        if isinstance(user_input, str) and self._session:
+        if (
+            isinstance(user_input, str)
+            and self._session
+            and self.app.config.memory.enabled
+            and self.app.config.memory.auto_recall
+            and not self._disable_retrieval
+        ):
             try:
-                results = self._memory.search_memories(user_input, top_k=5)
+                top_k = self.app.config.memory.top_k
+                results = self._memory.search_memories(user_input, top_k=top_k)
                 if results:
                     lines = ["## Relevant past memories"]
                     for r in results:
@@ -1140,30 +1342,23 @@ class AgentEngine:
         provider_kwargs = dict(api_key=config.api_key or "", endpoint=config.endpoint or None)
         provider = provider_cls(**provider_kwargs)
 
+        # If the provider supports native tool schemas (OpenAI/Anthropic/DeepSeek
+        # etc.), strip the prose TOOL_DESCRIPTIONS from system context to save
+        # tokens. The structured ``tools`` kwarg provides the same info.
+        if not hasattr(provider, 'supports_native_tools') or provider.supports_native_tools():
+            self._strip_agent_config_tool_descriptions()
+
         # Reset per-turn usage tracking
         self._turn_usages = []
 
         # Reset cancellation flag (adapter also resets it before calling)
         self._cancelled = False
 
-        # ── Agent loop: CoT + ReAct (思考 → 行动 → 观察) ──
+        # ── Agent loop: 思考 → Todo → 行动 (per-Round) ──
         is_anthropic = provider.is_anthropic_style()
         max_turns = self.current_agent.max_turns or 10
 
-        # Initialize ReAct phase section (first turn prompt)
-        cot_phase_init = (
-            "<!-- REACT_PHASE -->\n"
-            "## Turn 1 — Thought Phase (思考)\n"
-            "Begin this turn by reasoning step by step in `<thinking>`:\n"
-            "1. **Current state**: Analyze the user request and what needs to be done.\n"
-            "2. **Goal**: What should I accomplish this turn?\n"
-            "3. **Routing**: For the next action, choose by complexity:\n"
-            "   - Simple (1 tool call, 1 file) → direct tool + optional `TodoCreate` for tracking\n"
-            "   - Complex (multi-file, multi-step, research-heavy) → `Spawn(agent_type, prompt)`\n"
-            "   - Pure research → `Read/Grep/Glob/WebFetch` directly, or `explore/scout` subagent\n"
-            "4. **Plan when needed**: For multi-step work, create a todo plan first via "
-            "`TodoCreate`, then mark each todo as `in_progress` / `completed` as you go.\n"
-        )
+        cot_phase_init = "<!-- REACT_PHASE -->\n## Round 1 — 思考 → Todo → 行动\n"
         if not self.context.replace_system_section("REACT_PHASE", cot_phase_init):
             self.context.add_system(cot_phase_init)
 
@@ -1175,24 +1370,16 @@ class AgentEngine:
             # ── Thought Phase: update CoT reasoning guidance for this turn ──
             # Cleanup stale reminders that may have accumulated
             self.context.remove_system_by_marker("<!-- ROUTING_REMINDER -->")
+            self.context.remove_system_by_marker("<!-- PLAN_REMINDER -->")
             # Inject (or refresh) a nudge that prioritizes any unfinished todos
             # from this session. The marker is replaced in-place so the context
             # stays bounded — the agent always sees the current open list.
             self._refresh_pending_todos_nudge()
             if turn > 0:
-                cot_phase = (
-                    f"<!-- REACT_PHASE -->\n"
-                    f"## Turn {turn + 1} — Thought Phase (思考)\n"
-                    "Begin this turn by reasoning step by step in `<thinking>`:\n"
-                    "1. **Current state**: What just happened? What results do I have?\n"
-                    "2. **Goal**: What should I accomplish this turn?\n"
-                    "3. **Routing**: For the next action, choose by complexity:\n"
-                    "   - Simple (1 tool call, 1 file) → direct tool + optional `TodoCreate` for tracking\n"
-                    "   - Complex (multi-file, multi-step, research-heavy) → `Spawn(agent_type, prompt)`\n"
-                    "4. **Plan when needed**: For multi-step work, advance todos via `TodoUpdate` "
-                    "and delegate substantial items via `Spawn`.\n"
+                self.context.replace_system_section(
+                    "REACT_PHASE",
+                    f"<!-- REACT_PHASE -->\n## Round {turn + 1} — 思考 → Todo → 行动\n",
                 )
-                self.context.replace_system_section("REACT_PHASE", cot_phase)
 
             self._pending_thinking_blocks = []
 
@@ -1214,6 +1401,8 @@ class AgentEngine:
                     _original_cb = self.on_text_chunk
                     def _stream_wrapper(text: str) -> None:
                         self._streaming_used = True
+                        if self._cancelled:
+                            raise TurnCancelledError()
                         _original_cb(text)
                     stream_cb = _stream_wrapper
                 else:
@@ -1291,6 +1480,9 @@ class AgentEngine:
                     logger.exception(f"Error during chat() fallback turn {turn+1}: {e}")
                     yield StreamEvent.error(safe_error_msg(e))
                     break
+            except TurnCancelledError:
+                yield StreamEvent.text_delta("\n\n*Turn cancelled*\n\n")
+                return
             except Exception as e:
                 ctx_msgs = len(self.context.messages)
                 ctx_tokens = self.context._token_count
@@ -1302,6 +1494,12 @@ class AgentEngine:
                 yield StreamEvent.error(f"Provider error (turn {turn+1}): {safe_error_msg(e)}")
                 break
 
+            # Check cancellation after provider call (covers non-streaming
+            # responses and cases where on_text_chunk was never called).
+            if self._cancelled:
+                yield StreamEvent.text_delta("\n\n*Turn cancelled*\n\n")
+                return
+
             # Track usage
             self._turn_usages.append(turn_usage)
             if turn_usage:
@@ -1327,7 +1525,7 @@ class AgentEngine:
             # Log the raw model response so developers can verify the
             # model is actually emitting ``<thinking>`` markers (and not
             # bleeding planning prose into the visible answer).  Goes
-            # to the onecode root logger → ~/.cdh/logs/cdh.log when
+            # to the onecode root logger → ~/.onecode/logs/onecode.log when
             # ``setup_logging(DEBUG)`` is in effect.
             logger.debug(
                 "RAW_RESPONSE turn=%d text_len=%d first_200=%r "
@@ -1362,14 +1560,15 @@ class AgentEngine:
 
             self.iterations += 1
 
-            if not tool_uses:
-                if not self._streaming_used:
-                    if clean_text.strip():
-                        for i in range(0, len(clean_text), 12):
-                            yield StreamEvent.text_delta(clean_text[i:i + 12])
-                    elif self._last_user_msg:
-                        yield StreamEvent.text_delta(self._last_user_msg)
+            # Always yield text content as TEXT_DELTA, regardless of tool uses.
+            # Without this, subagent text is consumed silently when it also
+            # emits tool calls — the text goes to context but never reaches
+            # _spawn_subagent_async_streaming / the subagent_chunk stream.
+            if not self._streaming_used and clean_text.strip():
+                for i in range(0, len(clean_text), 12):
+                    yield StreamEvent.text_delta(clean_text[i:i + 12])
 
+            if not tool_uses:
                 # ── Store conversation in long-term memory ──
                 if self._session:
                     try:
@@ -1382,6 +1581,90 @@ class AgentEngine:
                         )
                     except Exception as e:
                         logger.warning("Memory store failed: %s", e)
+
+                # ── Force continuation if todos remain ──
+                # After subagents complete, the LLM may stop calling tools
+                # because the structured output strongly signals "done".
+                # If there are still pending/in-progress todos, inject a
+                # forceful continuation nudge and loop again instead of
+                # exiting the turn loop.
+                self._empty_tool_turns += 1
+                if self._empty_tool_turns >= 3:
+                    logger.warning(
+                        "LLM produced %d consecutive empty turns with %d "
+                        "remaining todos — breaking loop",
+                        self._empty_tool_turns,
+                        sum(1 for t in self._todo_manager.list_todos()
+                            if t.get("status") in ("pending", "in_progress")),
+                    )
+                    break
+                if self._has_pending_todos():
+                    open_count = sum(
+                        1 for t in self._todo_manager.list_todos()
+                        if t.get("status") in ("pending", "in_progress")
+                    )
+                    logger.info(
+                        "LLM stopped calling tools but %d pending todos remain — "
+                        "injecting FORCE_CONTINUE nudge (empty_tool_turns=%d)",
+                        open_count, self._empty_tool_turns,
+                    )
+                    # Auto-advance: since the LLM is stalled, find the next
+                    # pending todo and inject a direct instruction.
+                    next_todo = None
+                    for t in self._todo_manager.list_todos():
+                        if t.get("status") == "pending":
+                            next_todo = t
+                            break
+                    if next_todo:
+                        lines = [
+                            "# Continue working",
+                            "",
+                            f"The next pending todo is `{next_todo['id']}`: "
+                            f"{next_todo.get('subject', '')}",
+                            "",
+                            "Execute it now. Do NOT summarise or stop.",
+                        ]
+                        self.context.add_message(
+                            "user",
+                            [{"type": "text", "text": "\n".join(lines)}],
+                        )
+                    else:
+                        lines = [
+                            "<!-- FORCE_CONTINUE -->",
+            "## CRITICAL: Unfinished todos detected",
+            "You stopped without completing all planned todos.",
+            "You MUST continue working:",
+            "1. Call TodoUpdate(status=\"completed\") for any finished work.",
+            "2. Then Spawn or execute the next pending todo.",
+            "3. Repeat until ALL todos are Done.",
+            "Do NOT stop. Do NOT summarise. Keep executing.",
+                        ]
+                        self.context.add_message(
+                            "user",
+                            [{"type": "text", "text": "\n".join(lines)}],
+                        )
+                    continue
+                # No pending todos and no tool calls: work appears done.
+                # Guard: if no todos were ever created after multiple rounds,
+                # the agent may have done work without tracking it. Inject a
+                # one-time confirmation prompt before giving the final break.
+                all_todos = self._todo_manager.list_todos()
+                if not all_todos and self.iterations > 1:
+                    confirm_lines = [
+                        "# Final check",
+                        "",
+                        "You haven't created any todos in this session. "
+                        "Are you sure all work is complete?",
+                        "",
+                        "If work remains → `TodoCreate` and continue.",
+                        "If done → output a visible summary of what you accomplished.",
+                    ]
+                    self.context.add_message(
+                        "user",
+                        [{"type": "text", "text": "\n".join(confirm_lines)}],
+                    )
+                    self._empty_tool_turns += 1
+                    continue
                 break
 
             # Emit ToolEvents (Clawd-Code pattern) and StreamEvents for TUI
@@ -1397,6 +1680,9 @@ class AgentEngine:
                 yield StreamEvent.tool_call_complete(tu["id"], tu["name"], tu["input"])
 
             for tu in tool_uses:
+                if self._cancelled:
+                    yield StreamEvent.text_delta("\n\n*Turn cancelled*\n\n")
+                    return
                 logger.info(f"Executing tool: {tu['name']} (id={tu['id']})")
 
                 # Spawn tool: forward subagent text deltas to the TUI as
@@ -1416,27 +1702,82 @@ class AgentEngine:
                     else:
                         subagent_type = tu["input"].get("agent_type", "general")
                         subagent_prompt = tu["input"].get("prompt", "")
+                        _sp_id = tu["id"]
+                        _sp_bytes_fwd = 0
+                        _sp_chunk_count = 0
+                        logger.debug(
+                            "[SPAWN-PARENT %s] start subagent_type=%s prompt_len=%d "
+                            "tool_id=%s cancelled=%s",
+                            _sp_id, subagent_type, len(subagent_prompt),
+                            _sp_id, self._cancelled,
+                        )
                         is_failed = False
                         error_msg = ""
                         yield StreamEvent.subagent_start(subagent_type, tu["id"], subagent_prompt)
                         accumulated: list[str] = []
-                        async for sub_event, sub_text in self._spawn_subagent_async_streaming(
-                            subagent_type, subagent_prompt
-                        ):
-                            if not sub_text:
-                                continue
-                            if sub_event.type == StreamEventType.SUBAGENT_END:
-                                # Carry status/error from subagent_end event
-                                if hasattr(sub_event, "subagent_status") and sub_event.subagent_status == "failed":
-                                    is_failed = True
-                                    error_msg = sub_event.subagent_error or ""
-                                continue  # 修复 Bug 1: 不 append final combined text（避免文本重复）
-                            if sub_event.type == StreamEventType.SUBAGENT_THINKING:
-                                yield StreamEvent.subagent_thinking(tu["id"], sub_text)
-                                continue
-                            # TEXT_DELTA
-                            accumulated.append(sub_text)
-                            yield StreamEvent.subagent_chunk(tu["id"], sub_text)
+                        try:
+                            async for sub_event, sub_text in self._spawn_subagent_async_streaming(
+                                subagent_type, subagent_prompt, subagent_id=tu["id"]
+                            ):
+                                _sp_chunk_count += 1
+                                if self._cancelled:
+                                    logger.debug(
+                                        "[SPAWN-PARENT %s] cancelled mid-iter "
+                                        "chunk=%d → break", _sp_id, _sp_chunk_count)
+                                    break
+                                if sub_event.type == StreamEventType.SUBAGENT_END:
+                                    if hasattr(sub_event, "subagent_status") and sub_event.subagent_status == "failed":
+                                        is_failed = True
+                                        error_msg = sub_event.subagent_error or ""
+                                    logger.debug(
+                                        "[SPAWN-PARENT %s] recv SUBAGENT_END "
+                                        "status=%s → continue",
+                                        _sp_id, getattr(sub_event, "subagent_status", "?"),
+                                    )
+                                    continue  # 修复 Bug 1: 不 append final combined text（避免文本重复）
+                                if sub_event.type == StreamEventType.SUBAGENT_THINKING:
+                                    yield StreamEvent.subagent_thinking(tu["id"], sub_text)
+                                    continue
+                                # Structured subagent tool events: forward as-is
+                                # (they already carry subagent_id=tu["id"]) so the
+                                # ACP emits tool_call/tool_call_update sessionUpdates
+                                # tagged with subagentId and the TUI renders real
+                                # ToolCall cards inside the SubAgent widget.
+                                if sub_event.type in (
+                                    StreamEventType.SUBAGENT_TOOL_CALL,
+                                    StreamEventType.SUBAGENT_TOOL_RESULT,
+                                ):
+                                    yield sub_event
+                                    continue
+                                if not sub_text:
+                                    continue
+                                accumulated.append(sub_text)
+                                _sp_bytes_fwd += len(sub_text)
+                                if _sp_chunk_count <= 5 or _sp_chunk_count % 50 == 0:
+                                    logger.debug(
+                                        "[SPAWN-PARENT %s] fwd chunk#%d bytes=%d "
+                                        "total=%d",
+                                        _sp_id, _sp_chunk_count, len(sub_text),
+                                        _sp_bytes_fwd,
+                                    )
+                                yield StreamEvent.subagent_chunk(tu["id"], sub_text)
+                        except asyncio.CancelledError:
+                            logger.debug(
+                                "[SPAWN-PARENT %s] CancelledError → subagent_end "
+                                "failed=cancelled + re-raise", _sp_id)
+                            yield StreamEvent.subagent_end(
+                                tu["id"],
+                                agent_type=subagent_type,
+                                status="failed",
+                                error="cancelled",
+                            )
+                            raise
+                        logger.debug(
+                            "[SPAWN-PARENT %s] subagent done fwd_chunks=%d "
+                            "bytes_fwd=%d is_failed=%s err=%r → yield subagent_end",
+                            _sp_id, _sp_chunk_count, _sp_bytes_fwd, is_failed,
+                            error_msg[:80],
+                        )
                         yield StreamEvent.subagent_end(
                             tu["id"],
                             agent_type=subagent_type,
@@ -1444,6 +1785,10 @@ class AgentEngine:
                             error=error_msg,
                         )
                         raw_output = "".join(accumulated)
+                        logger.debug(
+                            "[SPAWN-PARENT %s] formatting result raw_len=%d "
+                            "is_failed=%s", _sp_id, len(raw_output), is_failed,
+                        )
                         formatted = self._format_subagent_output(
                             subagent_type, subagent_prompt, raw_output
                         ) if not is_failed else (
@@ -1458,6 +1803,9 @@ class AgentEngine:
                             "content": formatted,
                             "raw_content": raw_output,
                         }
+                        # Auto-advance todo after subagent completes
+                        if not is_failed:
+                            self._auto_advance_after_spawn(subagent_prompt)
                 elif (self._plan_gate_mode != "off"
                       and not self._todo_manager.list_todos()
                       and tu["name"] in _EXECUTION_TOOLS
@@ -1488,16 +1836,17 @@ class AgentEngine:
                         self.context.add_system(
                             "<!-- PLAN_REMINDER -->\n"
                             "## Routing Decision\n"
-                            "Before your next action, choose the right tool based on complexity:\n\n"
-                            "**Simple / single-step work** → use `TodoCreate` to track a lightweight "
-                            "checklist item in the sidebar. Examples: 1 file edit, 1 Read, 1 Bash. "
-                            "The Todo widget shows progress to the user.\n\n"
-                            "**Complex / multi-step work** → use `Spawn(agent_type, prompt)` to "
-                            "delegate to a focused subagent. Examples: cross-file refactor, multi-"
-                            "file feature, research requiring 3+ tool calls, work needing isolated "
-                            "context. The subagent encapsulates work and returns structured output.\n\n"
-                            "**Default**: When unsure → `Spawn`. Todo is for visible progress on "
-                            "simple items; Spawn is for substantial work.\n"
+                            "Every task is a todo: create it with `TodoCreate` first (it "
+                            "persists to .cdh/todos.json and shows in the sidebar Plan).\n"
+                            "Then route EXECUTION by complexity:\n\n"
+                            "**Simple / single-step** → execute the todo directly with "
+                            "`Read`/`Edit`/`Bash`, then `TodoUpdate(status=\"completed\")`.\n\n"
+                            "**Complex / multi-step / needs isolated context** → "
+                            "`Spawn(agent_type, prompt)` delegates to a focused subagent; "
+                            "on return, `TodoUpdate(status=\"completed\")`.\n\n"
+                            "**Plan vs execution**: TodoCreate = planning (always); "
+                            "Spawn = execution delegation (complex only). They are not "
+                            "alternatives — Spawn executes a todo, it does not replace one.\n"
                         )
                         result = await self._execute_tool(tu)
                 else:
@@ -1509,17 +1858,19 @@ class AgentEngine:
                             self.context.add_system(
                                 "<!-- ROUTING_REMINDER -->\n"
                                 "You've used direct execution tools repeatedly. Pause and decide:\n"
-                                "- If this is a single-step trivial change → continue, but "
-                                "consider `TodoCreate` to surface progress in the sidebar.\n"
+                                "- Is this work tracked by a todo? If not, `TodoCreate` first.\n"
+                                "- If the todo is a single-step trivial change → continue, then "
+                                "`TodoUpdate(status=\"completed\")`.\n"
                                 "- If this work involves >1 tool call, multiple files, or "
                                 "research → STOP direct execution and delegate via "
                                 "`Spawn(agent_type=\"general\", prompt=\"...\")` instead. The "
-                                "subagent isolates context and returns a structured summary."
+                                "subagent isolates context and returns a structured summary; "
+                                "then mark the todo completed."
                             )
                 result_str = str(result.get("content", ""))
                 is_error = result.get("is_error", False)
                 category = result.get("category", "unknown")
-                # For Task tools, use raw subagent output for TUI display
+                # For Spawn tools, use raw subagent output for TUI display
                 # (no SUMMARY/CHANGES/… structured wrapper)
                 tui_content = str(result.get("raw_content", result_str))
 
@@ -1627,6 +1978,13 @@ class AgentEngine:
                         path=tu["input"].get("path", ""),
                         command=tu["input"].get("command", "")[:200],
                     )
+                    # Generator resumes here after approval. The approved tool
+                    # may have mutated todos (e.g. TodoUpdate via resolve_approval),
+                    # flushing _plan_dirty so the TUI stays in sync.
+                    if self._plan_dirty:
+                        for event in self._emit_plan_update():
+                            yield event
+                        self._plan_dirty = False
                 else:
                     from onecode.models.messages import ToolCategory as MsgToolCategory
                     try:
@@ -1664,6 +2022,9 @@ class AgentEngine:
                             yield event
                         self._plan_dirty = False
 
+            # Tools were called this turn — reset the empty-turn counter
+            self._empty_tool_turns = 0
+
             if self._cancelled:
                 yield StreamEvent.text_delta("\n\n*Turn cancelled*\n\n")
                 return
@@ -1672,7 +2033,29 @@ class AgentEngine:
             f"turn {i+1}: {u.get('total_tokens', '?')} tokens"
             for i, u in enumerate(self._turn_usages) if u
         )
-        logger.info(f"Chat stream complete after {self.iterations} turn(s). Usage: [{usage_summary}]")
+        logger.info(f"Chat stream complete after {self.iterations} round(s). Usage: [{usage_summary}]")
+
+        # ── Final summary fallback ──
+        # If the last round had no visible text (all reasoning was inside
+        # <thinking>), emit a deterministic summary so the user always sees
+        # a completion report — no extra LLM round-trip needed.
+        if not self._cancelled:
+            last_msg = self.context.messages[-1] if self.context.messages else None
+            has_visible = False
+            if last_msg and last_msg.get("role") == "assistant":
+                content = last_msg.get("content", "")
+                if isinstance(content, str):
+                    has_visible = bool(content.strip())
+                elif isinstance(content, list):
+                    has_visible = any(
+                        isinstance(block, dict)
+                        and block.get("type") == "text"
+                        and block.get("text", "").strip()
+                        for block in content
+                    )
+            if not has_visible:
+                summary = self._build_completion_summary()
+                yield StreamEvent.text_delta(summary)
 
     def has_pending_approval(self) -> bool:
         """Check if there's a pending approval request from ASK permission."""
@@ -1746,6 +2129,7 @@ class AgentEngine:
         """Reset ReAct loop state for a fresh cycle."""
         self._react_phase = "thought"
         self._direct_execution_count = 0
+        self._empty_tool_turns = 0
         self._plan_gate_fired = False
         # Invalidate the plan-emit dedupe cache so the next chat_stream
         # always produces a fresh snapshot for the TUI.
@@ -1832,7 +2216,7 @@ class AgentEngine:
         return self._format_subagent_output(agent_type, prompt, result)
 
     async def _spawn_subagent_async_streaming(
-        self, agent_type: str, prompt: str
+        self, agent_type: str, prompt: str, subagent_id: str = ""
     ) -> AsyncIterator[tuple[StreamEvent, str]]:
         """Streaming variant of :meth:`_spawn_subagent_async`.
 
@@ -1855,51 +2239,281 @@ class AgentEngine:
 
         sub_engine._subagent_depth = self._subagent_depth + 1
 
-        # Inherit parent context: project info, skills
+        # Inherit parent context: project info (but NOT full skill content,
+        # which contains Master Orchestrator instructions that conflict with
+        # the subagent role). The subagent's own _load_skills() will load
+        # only non-conflicting reference info via its own SkillLoader.
         sub_engine._project_context_loaded = self._project_context_loaded
         sub_engine._project_config = dict(self._project_config)
-        sub_engine._skills_loaded = True
-        for skill in self._skill_loader.get_enabled():
-            if skill.content not in (m.content for m in sub_engine.context.messages if m.role == "system"):
-                sub_engine.context.add_system(skill.content)
+        sub_engine._skills_loaded = False
+
+        # Inherit the parent's already-built codebase engine so the subagent
+        # does NOT re-run the full project index (CodebaseIndexer.index()
+        # is a synchronous chunk loop that would otherwise block the event
+        # loop for the duration of indexing and freeze streaming/cancel).
+        # Sharing the instance also avoids duplicate SQLite writes.
+        sub_engine._codebase_engine = self._codebase_engine
+        logger.debug(
+            "[SA-STREAM %s] inheriting codebase_engine from parent: %s",
+            agent_type, "shared" if self._codebase_engine is not None else "none",
+        )
 
+        # CRITICAL: disable codebase auto-retrieval + memory recall inside
+        # the subagent.  Production logs prove that every Spawn hung here:
+        # the subagent's ``chat_stream`` re-ran ``CodebaseIndexer.index()``
+        # (a 2.3–2.6s synchronous loop, no await yield points) and then
+        # ``CodebaseRetriever._retrieve_embedding()`` issued one ``httpx``
+        # POST per chunk (30s timeout each, no effective cap), so a 148-
+        # chunk project could block the event loop for ~minutes — during
+        # which ``on_text_chunk`` never fires (no stream output) and
+        # ``CancelledError`` injected by ``prompt_task.cancel()`` cannot
+        # propagate (cannot be stopped).  A subagent executes a specific
+        # prompt handed down by the parent; it does not need project-level
+        # codebase seeding or memory recall.
+        sub_engine._disable_retrieval = True
+        logger.debug(
+            "[SA-STREAM %s] set _disable_retrieval=True (subagent skips "
+            "codebase auto-retrieval + memory recall)", agent_type,
+        )
+
+        # Do NOT propagate parent TUI-facing callbacks to the sub_engine.
+        # - on_tool_call_delta: would fire the ACP's _on_tool_call_delta for
+        #   the subagent's inner tools (Read/Bash/...), leaking their NAMES
+        #   into the MAIN conversation as orphaned in_progress cards while
+        #   the RESULT only reaches the SubAgent widget via the stream path
+        #   below (tool_call_start/tool_result -> text_delta -> subagent_chunk).
+        # - on_thinking: would append subagent thinking into the PARENT's
+        #   _pending_thinking_blocks, polluting the parent's persisted session.
+        # The subagent's tool calls/thinking are already relayed to the
+        # SubAgent widget via SUBAGENT_CHUNK / SUBAGENT_THINKING (see the
+        # consumer loop below). on_event is left propagated: the ACP does
+        # not wire it, so it is None on the parent and a no-op here.
+        if self.on_event is not None:
+            sub_engine.on_event = self.on_event
+
+        # Apply the requested agent_type's config (role description,
+        # response-style / <thinking> tags, tool allow/deny list, REACT_CYCLE)
+        # as the AGENT_CONFIG system section.
         sub_engine.set_agent(agent_type)
 
         # Track child so parent cancellation cascades
         self._child_engines.append(sub_engine)
 
+        # ── Real-time streaming via asyncio.Queue ──
+        # on_text_chunk puts provider tokens into the queue as they arrive,
+        # and a background task puts chat_stream events into the same queue.
+        # The main loop reads from the queue and yields (event, text) pairs,
+        # giving the TUI live subagent output instead of "等待输出".
+        _queue: asyncio.Queue[tuple[str, object]] = asyncio.Queue()
+        _sa_log_prefix = f"[SA-STREAM {agent_type} depth={self._subagent_depth + 1}]"
+        _sa_total_bytes = 0
+        _sa_chunk_count = 0
+        _sa_text_count = 0
+        _sa_first_byte_logged = False
+
+        def _on_subagent_text(text: str) -> None:
+            nonlocal _sa_total_bytes, _sa_text_count, _sa_first_byte_logged
+            try:
+                _queue.put_nowait(("text", text))
+                _sa_text_count += 1
+                _sa_total_bytes += len(text)
+                if not _sa_first_byte_logged:
+                    _sa_first_byte_logged = True
+                    logger.debug(
+                        "%s on_text_chunk FIRST token bytes=%d (text_count so far=%d)",
+                        _sa_log_prefix, len(text), _sa_text_count,
+                    )
+                if _sa_text_count % 20 == 0:
+                    logger.debug(
+                        "%s on_text_chunk progress text_calls=%d total_bytes=%d "
+                        "queued=%d",
+                        _sa_log_prefix, _sa_text_count, _sa_total_bytes,
+                        _queue.qsize(),
+                    )
+            except Exception as e:
+                logger.warning("%s on_text_chunk queue.put failed: %s", _sa_log_prefix, e)
+
+        sub_engine.on_text_chunk = _on_subagent_text
+        logger.debug("%s wiring on_text_chunk → queue (sub_engine id=%x)",
+                     _sa_log_prefix, id(sub_engine))
+
+        async def _run_chat_stream() -> None:
+            logger.debug("%s _run_chat_stream task started", _sa_log_prefix)
+            try:
+                async for chunk in sub_engine.chat_stream(prompt):
+                    await _queue.put(("event", chunk))
+            except asyncio.CancelledError:
+                logger.debug("%s _run_chat_stream CancelledError → queue(cancelled)",
+                             _sa_log_prefix)
+                await _queue.put(("cancelled", None))
+            except Exception as e:
+                logger.exception("%s _run_chat_stream exception: %s", _sa_log_prefix, e)
+                await _queue.put(("error", e))
+            finally:
+                logger.debug(
+                    "%s _run_chat_stream finally → queue(done) text=%d bytes=%d "
+                    "chunk_events=%d",
+                    _sa_log_prefix, _sa_text_count, _sa_total_bytes, _sa_chunk_count,
+                )
+                await _queue.put(("done", None))
+
+        _stream_task = asyncio.create_task(_run_chat_stream())
+        logger.debug("%s created _stream_task id=%x cancelled_flag=%s",
+                     _sa_log_prefix, id(_stream_task), self._cancelled)
+
         parts: list[str] = []
+        _streamed_via_text = False  # True once on_text_chunk has delivered tokens
+
         try:
-            async for chunk in sub_engine.chat_stream(prompt):
-                if isinstance(chunk, StreamEvent):
-                    if chunk.type == StreamEventType.TEXT_DELTA and chunk.text:
-                        parts.append(chunk.text)
-                        yield chunk, chunk.text
-                    elif chunk.type == StreamEventType.THINKING and chunk.thinking:
-                        # 修复 Bug 4: 转发思考块
-                        yield chunk, chunk.thinking
-                else:
-                    if chunk:
-                        parts.append(chunk)
-        except Exception as e:
-            logger.exception(f"Subagent error: {e}")
-            err_text = (
-                f"SUMMARY:\nSub-agent failed with error: {e}\n\n"
-                "CHANGES:\nNone.\n\nEVIDENCE:\nNone.\n\nRISKS:\nNone.\n\n"
-                f"BLOCKERS:\n{e}"
-            )
-            yield (StreamEvent.subagent_end(
-                "", agent_type=agent_type, status="failed", error=str(e),
-            ), err_text)
-        else:
+            logger.debug("%s entering queue.get() consumer loop", _sa_log_prefix)
+            while True:
+                item_type, item = await _queue.get()
+                _sa_chunk_count += 1
+                if _sa_chunk_count <= 5 or _sa_chunk_count % 50 == 0:
+                    logger.debug(
+                        "%s queue.get() #%d type=%s cancelled_flag=%s qsize=%d "
+                        "text=%d bytes=%d",
+                        _sa_log_prefix, _sa_chunk_count, item_type,
+                        self._cancelled, _queue.qsize(), _sa_text_count,
+                        _sa_total_bytes,
+                    )
+
+                if item_type == "text":
+                    _streamed_via_text = True
+                    parts.append(item)
+                    yield (StreamEvent.text_delta(item), item)
+
+                elif item_type == "event":
+                    chunk = item
+                    if isinstance(chunk, StreamEvent):
+                        if chunk.type == StreamEventType.TEXT_DELTA and chunk.text:
+                            # Skip TEXT_DELTA if tokens were already streamed
+                            # in real-time via on_text_chunk (avoids doubles).
+                            if not _streamed_via_text:
+                                if _sa_chunk_count <= 5:
+                                    logger.debug(
+                                        "%s TEXT_DELTA via event path (no "
+                                        "streamed_via_text) bytes=%d",
+                                        _sa_log_prefix, len(chunk.text),
+                                    )
+                                parts.append(chunk.text)
+                                yield (chunk, chunk.text)
+                            else:
+                                if _sa_chunk_count <= 3:
+                                    logger.debug(
+                                        "%s TEXT_DELTA skipped (already "
+                                        "streamed_via_text) bytes=%d",
+                                        _sa_log_prefix, len(chunk.text),
+                                    )
+                        elif chunk.type == StreamEventType.THINKING and chunk.thinking:
+                            logger.debug("%s THINKING event bytes=%d",
+                                         _sa_log_prefix, len(chunk.thinking))
+                            yield (chunk, chunk.thinking)
+                        elif chunk.type == StreamEventType.TOOL_CALL_START:
+                            logger.debug("%s TOOL_CALL_START tool=%s",
+                                         _sa_log_prefix, chunk.tool_name)
+                            yield (StreamEvent.subagent_tool_call(
+                                subagent_id, "start", chunk.tool_id,
+                                chunk.tool_name, chunk.tool_category,
+                            ), "")
+                        elif chunk.type == StreamEventType.TOOL_CALL_COMPLETE:
+                            logger.debug("%s TOOL_CALL_COMPLETE tool=%s",
+                                         _sa_log_prefix, chunk.tool_name)
+                            yield (StreamEvent.subagent_tool_call(
+                                subagent_id, "complete", chunk.tool_id,
+                                chunk.tool_name, chunk.tool_category,
+                                chunk.tool_args,
+                            ), "")
+                        elif chunk.type == StreamEventType.TOOL_RESULT:
+                            logger.debug("%s TOOL_RESULT tool=%s",
+                                         _sa_log_prefix, chunk.tool_name)
+                            yield (StreamEvent.subagent_tool_result(
+                                subagent_id, chunk.tool_id, chunk.tool_name,
+                                chunk.result_content, chunk.result_is_error,
+                                chunk.result_category,
+                            ), "")
+                        elif chunk.type == StreamEventType.ERROR:
+                            logger.debug("%s ERROR event msg=%s",
+                                         _sa_log_prefix, chunk.error_message)
+                            text = f"\n[Error: {chunk.error_message}]\n"
+                            yield (StreamEvent.text_delta(text), text)
+                    else:
+                        if chunk:
+                            parts.append(chunk)
+
+                elif item_type == "done":
+                    logger.debug("%s queue.get()=done → break loop", _sa_log_prefix)
+                    break
+
+                elif item_type == "cancelled":
+                    logger.debug(
+                        "%s queue.get()=cancelled → yield subagent_end "
+                        "failed=cancelled", _sa_log_prefix)
+                    yield (StreamEvent.subagent_end(
+                        "", agent_type=agent_type, status="failed", error="cancelled",
+                    ), "")
+                    return
+
+                elif item_type == "error":
+                    logger.exception("%s queue.get()=error: %s", _sa_log_prefix, item)
+                    err_text = (
+                        f"SUMMARY:\nSub-agent failed with error: {item}\n\n"
+                        "CHANGES:\nNone.\n\nEVIDENCE:\nNone.\n\nRISKS:\nNone.\n\n"
+                        f"BLOCKERS:\n{item}"
+                    )
+                    yield (StreamEvent.subagent_end(
+                        "", agent_type=agent_type, status="failed", error=str(item),
+                    ), err_text)
+                    return
+
+        except asyncio.CancelledError:
+            logger.debug("%s consumer loop CancelledError → subagent_end", _sa_log_prefix)
+            # Parent cancelled — emit subagent_end so the TUI widget
+            # transitions out of "running", then re-raise.
             yield (StreamEvent.subagent_end(
-                "", agent_type=agent_type, status="completed",
-            ), "".join(parts))
+                "", agent_type=agent_type, status="failed", error="cancelled",
+            ), "")
+            raise
         finally:
-            # Clean up completed subagent to prevent memory leak
+            logger.debug(
+                "%s consumer finally: stream_task.done=%s cancelled_flag=%s "
+                "text=%d bytes=%d chunk_events=%d",
+                _sa_log_prefix, _stream_task.done(), self._cancelled,
+                _sa_text_count, _sa_total_bytes, _sa_chunk_count,
+            )
+            if not _stream_task.done():
+                logger.debug("%s finally: cancelling _stream_task (still running)",
+                             _sa_log_prefix)
+                _stream_task.cancel()
+                try:
+                    logger.debug("%s finally: awaiting _stream_task ...",
+                                 _sa_log_prefix)
+                    await _stream_task
+                    logger.debug("%s finally: await _stream_task returned cleanly",
+                                 _sa_log_prefix)
+                except asyncio.CancelledError:
+                    logger.debug("%s finally: await _stream_task CancelledError",
+                                 _sa_log_prefix)
+                except Exception as e:
+                    logger.debug("%s finally: await _stream_task exception=%s",
+                                 _sa_log_prefix, e)
             if sub_engine in self._child_engines:
                 self._child_engines.remove(sub_engine)
-    
+            logger.debug(
+                "%s finally done text=%d bytes=%d chunk_events=%d",
+                _sa_log_prefix, _sa_text_count, _sa_total_bytes, _sa_chunk_count,
+            )
+
+        # Normal completion
+        yield (StreamEvent.subagent_end(
+            "", agent_type=agent_type, status="completed",
+        ), "".join(parts))
+
+    _SUBAGENT_SECTION_RE = re.compile(
+        r'^(SUMMARY|CHANGES|EVIDENCE|RISKS|BLOCKERS):\s*$',
+        re.IGNORECASE | re.MULTILINE,
+    )
+
     def _format_subagent_output(self, agent_type: str, prompt: str, result: str) -> str:
         """Format sub-agent output in DeepSeek-TUI structured contract format.
         
@@ -1910,32 +2524,25 @@ class AgentEngine:
         RISKS: what could go wrong / what the parent should double-check
         BLOCKERS: what stopped you; "None." if you finished cleanly
         """
-        # Try to detect if the result already has structured sections
-        result_lower = result.lower()
-        has_sections = all(
-            tag.lower() in result_lower 
-            for tag in ["summary", "changes", "evidence", "risks", "blockers"]
-        )
-        
+        # Detect structured sections via line-start regex, not substring match
+        has_sections = self._SUBAGENT_SECTION_RE.search(result) is not None
+
         if has_sections:
-            # Already structured — just ensure proper formatting
             return result
-        else:
-            # Add structured wrapper around raw result
-            return (
-                f"SUMMARY:\n{agent_type.capitalize()} agent completed task: {prompt[:200]}\n\n"
-                f"CHANGES:\nNone detected.\n\n"
-                f"EVIDENCE:\n- See detailed output below\n\n"
-                f"RISKS:\nNone identified.\n\n"
-                f"BLOCKERS:\nNone.\n\n"
-                f"--- Raw Output ---\n{result}"
-            )
+
+        return (
+            f"SUMMARY:\n{agent_type.capitalize()} agent completed task: {prompt[:200]}\n\n"
+            f"CHANGES:\nNone detected.\n\n"
+            f"EVIDENCE:\n- See detailed output below\n\n"
+            f"RISKS:\nNone identified.\n\n"
+            f"BLOCKERS:\nNone.\n\n"
+            f"--- Raw Output ---\n{result}"
+        )
 
     def spawn_subagent(self, agent_type: str, prompt: str) -> dict:
         if self.current_agent.permission_task == AgentPermission.DENY:
             return {"success": False, "error": "Subagent denied"}
         import asyncio
-        import concurrent.futures
         try:
             loop = asyncio.get_event_loop()
             if loop.is_running():
@@ -1966,10 +2573,10 @@ class AgentEngine:
         if session.messages:
             self.context.load_from_session(session.messages)
         if session.todos:
-            self._todo_manager = TodoManager.from_dict({
+            self._todo_manager.reload_from_dict({
                 "todos": session.todos,
                 "id_counter": len(session.todos),
-            }, on_change=self._on_todo_change)
+            })
         # Restore context usage stats
         self._restore_session_stats(session)
 
@@ -1999,10 +2606,10 @@ class AgentEngine:
         self._session = session
         self.context.load_from_session(session.messages)
         if session.todos:
-            self._todo_manager = TodoManager.from_dict({
+            self._todo_manager.reload_from_dict({
                 "todos": session.todos,
                 "id_counter": len(session.todos),
-            }, on_change=self._on_todo_change)
+            })
             self._inject_loaded_tasks_into_context()
         # Restore context usage stats
         self._restore_session_stats(session)
@@ -2055,11 +2662,17 @@ class AgentEngine:
             self._turn_usages = list(restored_turns)
 
     def save_todos_to_project(self) -> None:
-        """Save todos to .cdh/todos.json in the project directory."""
+        """Save todos to .cdh/todos.json — uses find_cdh_dir_for_todos
+        so sub-projects never overwrite a parent project's todos."""
         from onecode.agent.cdh_loader import CdhProjectLoader
-        cdh_dir = CdhProjectLoader.find_cdh_dir(self._project_dir)
+        cdh_dir = CdhProjectLoader.find_cdh_dir_for_todos(self._project_dir)
         if cdh_dir is None:
-            return
+            cdh_dir = self._project_dir / CdhProjectLoader.CDH_DIRNAME
+            try:
+                cdh_dir.mkdir(parents=True, exist_ok=True)
+            except Exception as e:
+                logger.warning("Failed to create .cdh directory: %s", e)
+                return
         try:
             tm_data = self._todo_manager.to_dict()
             CdhProjectLoader.save_todos(cdh_dir, tm_data)
@@ -2067,17 +2680,19 @@ class AgentEngine:
             logger.warning("Failed to save todos to .cdh: %s", e)
 
     def load_todos_from_project(self) -> None:
-        """Restore todos from .cdh/todos.json (with legacy tasks.json fallback)."""
+        """Restore todos from .cdh/todos.json — uses find_cdh_dir_for_todos
+        so sub-projects never accidentally load a parent project's todos.
+        If todos are found, the ``<!-- NEW_SESSION_HINT -->`` marker is
+        removed from the system context (it only applies to blank sessions)."""
         from onecode.agent.cdh_loader import CdhProjectLoader
-        cdh_dir = CdhProjectLoader.find_cdh_dir(self._project_dir)
+        cdh_dir = CdhProjectLoader.find_cdh_dir_for_todos(self._project_dir)
         if cdh_dir is None:
             return
         try:
             data = CdhProjectLoader.load_todos(cdh_dir)
             if data and (data.get("tasks") or data.get("todos")):
-                self._todo_manager = TodoManager.from_dict(
-                    data, on_change=self._on_todo_change
-                )
+                self._todo_manager.reload_from_dict(data)
+                self.context.remove_system_by_marker("<!-- NEW_SESSION_HINT -->")
         except Exception as e:
             logger.warning("Failed to load todos from .cdh: %s", e)