qi-coding-agent 0.1.0__py3-none-any.whl

qi_agent/runtime.py

@@ -0,0 +1,1940 @@
+"""AutoRuntime(runtime.py):manual/auto + @点名 + 每轮重新路由 + 会话 JSONL 持久化。
+
+stream(): 一次用户输入 → 事件(CLI/TUI/HTTP 共享的 consumer 源)。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Iterable
+
+from . import paths
+from .auth import AuthOverride, AuthStore, resolve_key
+from .compaction import (
+    DEFAULT_KEEP_RECENT_TOKENS,
+    DEFAULT_RESERVE_TOKENS,
+    branch_to_summarize,
+    compact,
+    estimate_tokens,
+    messages_tokens,
+    prepare_compaction,
+    should_compact,
+    summarize_branch,
+    summary_context_message,
+)
+from .abort import AbortSignal
+from .config import (ProviderConfig, ResolvedModel, load_config, resolve_default_model,
+                     resolve_model, resolve_router_model)
+from .extensions import (
+    CommandRegistry,
+    ExtensionBus,
+    ExtensionContext,
+    ExtensionUi,
+    FlagRegistry,
+    ModelRegistryView,
+    ModelView,
+    RendererRegistry,
+    SessionView,
+    CliCommandRegistry,
+)
+from .llm import (
+    DEFAULT_THINKING_LEVEL,
+    ChatMessage,
+    LiteLLMClient,
+    LLMClient,
+    ThinkingLLMClient,
+    chat_message_from_dict,
+    normalize_thinking_level,
+)
+from .loader import LoadError, load_top_level_skills, resolve_base_prompt
+from .system_prompt import build_system_prompt, default_base_prompt
+from .models import AgentEvent
+from .registry import CapabilityRegistry, ToolCatalog, discover_extensions
+from .runner import AgentRunner, RunnerSettings, RunSpec
+from .session import (MODEL_CHANGE, THINKING_LEVEL_CHANGE, Session, SessionStore,
+                      context_settings, has_title)
+from .titling import suggest_title
+from .settings import (default_tools, extension_dirs, load_settings, load_settings_by_scope,
+                       branch_summary_skip_prompt, model_thinking_level,
+                       resolve_project_trust, session_dir)
+from .tools import ToolContext, register_builtin_tools
+from .tools.shell import session_env
+
+
+#: core 里那个**唯一**的运行单元的标签(事件归属 + 会话 entry 的 `agent_id`)。
+#: 角色概念整体交给 qi-agents(E1.1/E15),所以 core 只需要一个固定名字。
+#: 选 "qi" 而不是 "general":基座提示词的身份就是 qi,而且它不再是“兼底角色”。
+CORE_AGENT_NAME = "qi"
+
+
+def _as_int(value: Any, default: int = 0) -> int:
+    """配置里的数字可能是字符串/None —— 收成 int,坏值回落默认(不抛)。"""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+@dataclass
+class RuntimeConfig:
+    workdir: Path
+    # 轮次与请求超时都不在这里:
+    #  · 轮次是 `QiRuntime(stop_after=…)` 的谓词(对齐 pi 的 shouldStopAfterTurn);
+    #  · 请求级超时/重试归 provider 层(settings.json 的 `retry.provider`,见 llm.py)。
+    #
+    # P-E4c 删掉了 `confidence_min`:那是 Dispatcher 的旋钮,而分派已移出 core(E15)。
+
+
+# 落盘工具结果的字符上限。tools/ 内置工具已自行截断(200 行 / 50k 字符),
+# 但插件工具可能不截断——落盘前再过一道上限,避免单个工具撑破会话文件。
+MAX_TOOL_ENTRY_CHARS = 8000
+MAX_TOOL_DETAILS_CHARS = 8000
+#: 自动命名最多等这么久(秒)。等不到就把落盘挂到回调上 —— 见 `_apply_title`。
+TITLE_WAIT_S = 2.0    # 与 result 同档:插件不该让会话文件无界增长
+
+#: 扩展用 `input` 的 `handled` 接管一轮、又没给 `text` 时的占位。
+#: 不给提示会让用户以为程序卡住了(`ctx.ui` 要到 P-E3 才有,现在没有别的展示通道)。
+INPUT_HANDLED_PLACEHOLDER = "(这一轮由扩展处理,没有文本输出)"
+
+
+def _salvaged(final_text: str, partial: str) -> str:
+    """收尾用哪段文本:正常结束用 `agent_end` 的全文,被硬取消时用流式累计的半截。"""
+    return final_text if final_text else partial
+
+
+def split_tool_list(text: str) -> list[str]:
+    """`"read, grep write"` → `["read", "grep", "write"]`(逗号 / 空格 / 顿号都行)。"""
+    return [part for part in text.replace(",", " ").replace("、", " ").split() if part]
+
+
+def parse_model_flag(spec: str) -> tuple[str, str | None]:
+    """`--model` 的写法对齐 pi:`provider/模型`,可以带 `:<思考级别>` 后缀。
+
+    → `("provider/模型", 思考级别或 None)`。**只有后缀是已知的思考级别才算** ——
+    否则模型 id 自带的冒号会被误切(如 `openrouter/x:free` 里的 `:free` 不是级别)。
+    """
+    from .llm import THINKING_LEVELS
+
+    text = spec.strip()
+    head, sep, tail = text.rpartition(":")
+    if sep and "/" in head and tail.strip().lower() in THINKING_LEVELS:
+        return head, tail.strip().lower()
+    if "/" not in text:
+        raise ValueError(f'`--model` 要写成 "provider/模型"(可带 ":<思考级别>"):收到 {spec!r}')
+    return text, None
+
+
+def tool_source(catalog: Any, name: str) -> str:
+    """工具名 → 来源(`builtin` / 扩展名 …)。`source_info` 只由 `register_tool` 盖章。"""
+    tool = catalog.get(name)
+    if tool is None:
+        return ""
+    return str((getattr(tool, "source_info", None) or {}).get("source") or "")
+
+
+class QiRuntime:
+    """装配好的一次性运行时(每进程一个):装载配置/插件/agents,提供 stream()。"""
+
+    def __init__(self, cwd: Path | None = None, runtime_cfg: RuntimeConfig | None = None,
+                 session_store: SessionStore | None = None,
+                 llm: LLMClient | None = None,
+                 skills_enabled: bool = True,
+                 thinking_level: str | None = None,
+                 stop_after: Callable[[int], bool] | None = None,
+                 extra_skill_paths: Iterable[Path] | None = None,
+                 extra_extension_paths: Iterable[Path] | None = None,
+                 approve_project: bool | None = None,
+                 has_ui: bool = False,
+                 ui_frontend: Any = None,
+                 mode: str | None = None,
+                 extension_flags: Iterable[str] | None = None,
+                 tools: str | None = None,
+                 exclude_tools: str | None = None,
+                 no_tools: bool = False,
+                 no_builtin_tools: bool = False,
+                 append_system_prompt: Iterable[str] | None = None,
+                 base_prompt_override: str | None = None,
+                 no_extensions: bool = False,
+                 no_context_files: bool = False,
+                 session_dir_path: Path | str | None = None,
+                 model_override: str | None = None,
+                 api_key: str | None = None,
+                 scoped_models: Iterable[str] | None = None):
+        self.cwd = Path(cwd) if cwd else Path.cwd()
+        # 旧版扁平布局 → ~/.qi/agent/(幂等;显式设了 QI_AGENT_HOME 时不动)
+        paths.ensure_layout()
+        self.cfg, self.config_files = load_config(self.cwd)
+        self.settings, self.settings_files = load_settings(self.cwd)
+        self._has_ui = has_ui          # `ctx.has_ui`:交互式前端=True,`-p`/脚本=False
+        #: 同一 runtime 对同一会话只发一次 `session_start`(见 `start_session`)
+        self._started_sessions: set[str] = set()
+        self.runtime_cfg = runtime_cfg or RuntimeConfig(workdir=self.cwd)
+        # 轮次政策由嵌入方给(对齐 pi 的 shouldStopAfterTurn):None = 不限
+        # (qi 自己不设上限 —— 钩子留着但生产代码不传,同 pi 定义了却不实现它)
+        self.stop_after = stop_after
+        self.workdir = self.runtime_cfg.workdir
+        # 基座:项目 .qi/SYSTEM.md > ~/.qi/agent/SYSTEM.md;都没有则空串
+        # (空串 = 用 system_prompt.py 里的代码内默认基座,见 docs/configuration.md)
+        self.base_prompt, self.base_prompt_source = resolve_base_prompt(self.cwd)
+        # `--system-prompt`:命令行直接给基座 —— 与 `.qi/SYSTEM.md` **同一语义**(整体替换)
+        if base_prompt_override and base_prompt_override.strip():
+            self.base_prompt, self.base_prompt_source = base_prompt_override.strip(), "cli"
+        # `--no-context-files/-nc`:关掉 AGENTS.md / CLAUDE.md 的注入
+        self._no_context_files = no_context_files
+        #: `-a` / `-na` 的原始三态(None = 没表态)。有表态时**不问** `project_trust` 事件
+        #: —— 用户当场的直接指令优先于程序化策略。
+        self._approve_flag = approve_project
+        #: 第二趟装载要用(`-e` 显式给的路径)。
+        self._extra_extension_paths = list(extra_extension_paths or ())
+        #: `ctx.reload()` 重扫技能时要用(同一次运行里 CLI 给的额外技能路径)。
+        self._extra_skill_paths = list(extra_skill_paths or ())
+        # `--models <patterns>`:本次运行 Ctrl+P 的轮换清单。**不回写 settings** ——
+        # 命令行给的东西不该静默落盘(要持久化走 TUI 的 `/scoped-models`)。
+        self.scoped_models: list[str] | None = (
+            [str(item).strip() for item in scoped_models if str(item).strip()]
+            if scoped_models is not None else None)
+        # `--append-system-prompt <text>`(可重复):追加到**每回合** system prompt 的末尾。
+        # 多段用空行连接;全空则 None(不占位)。
+        self.append_system_prompt = "\n\n".join(
+            part.strip() for part in (append_system_prompt or ())
+            if part and part.strip()) or None
+        if session_dir_path is not None:
+            # `--session-dir`:命令行优先于 settings.sessionDir(pi 同名旗标)
+            self.sessions = SessionStore(root=Path(session_dir_path).expanduser())
+        elif session_store is not None:
+            self.sessions = session_store
+        else:
+            # sessionDir(settings.json)覆盖默认会话目录;对齐 pi 的优先级链
+            override_dir = session_dir(self.settings, self.cwd)
+            self.sessions = SessionStore(root=override_dir) if override_dir else SessionStore()
+
+        self.catalog = ToolCatalog()
+        register_builtin_tools(self.catalog)
+        self.capabilities = CapabilityRegistry()
+        #: 启动提示 + handler 异常的汇总通道(runtime 不做 IO,前端自己决定怎么展示)。
+        #: 必须在 `ExtensionBus` **之前**建:总线拿它当 handler 异常的去处。
+        self.notes: list[str] = []
+        # 事件总线:扩展在 `register(api)` 里 `api.on(...)` 订阅的东西都落在这里。
+        # 零扩展时 `is_empty` = True,宿主可以据此跳过整条派发路径。
+        # 同一个对象也挂着**扩展之间**的消息频道(`api.events`)。
+        self.bus = ExtensionBus(notes=self.notes)
+        #: 扩展的工具集覆盖(`api.setActiveTools`)。None = 按 agent 的 `tools` 解析
+        self._tool_override: set[str] | None = None
+        # 信任门控(P-E1 / E16):未信任 → **不扫**项目级扩展(扩展是仓库控制的任意代码)。
+        # 提示不在这里打印(runtime 不做 IO):攒进 `self.notes`,由前端决定怎么展示。
+        #: 当前回合绑定的会话(`api.appendEntry` / `ctx.session_manager` 靠它读/写)。
+        #: 由 `stream()` 的 wrapper 设置并在 `finally` 里清掉。
+        self._active_session: Session | None = None
+        #: **选会话时就绑定的**那个会话(前端调 `bind_session()`)。与 `_active_session` 分开:
+        #: 后者只管一个回合,而换模型 / 换思考级别是**回合外**发生的(扩展在 handler 里
+        #: `api.setModel`、TUI 的 `/model`),那时也必须知道该往哪个文件里记一笔。
+        self._bound_session: Session | None = None
+        #: 上一轮**已还原过设置**的那个会话 id(见 `bind_session`)。
+        #:
+        #: 判据是"绑的会话换了没有",**不是**"这个 id 还原过没有":早先记的是一个
+        #: `set[str]`,于是同一 runtime 里 A → B → A 切回来时,A 不再还原 ——
+        #: 而一个 runtime 服务多个会话正是 web 的常态(`runtime_for` 按 cwd 缓存),
+        #: 表现是"切回会话 A,却还拿着 B 的模型"。同级重绑(每回合开跑前都会调一次)
+        #: 仍然不重复还原,那才是这个判据要防的事。
+        self._restored_session: str | None = None
+        #: `--model` / `--thinking`(或 `--model p/m:级别`)在命令行上给过 —— 命令行优先级
+        #: **高于**会话里记的旧值,所以这类运行不从会话恢复(见 `_restore_context_settings`)。
+        self._model_pinned = model_override is not None
+        #: 扩展主动发的消息(`api.sendMessage` / `sendUserMessage`),按**送达时机**分桶。
+        #: 元素是 `(文本, 来源扩展, 调用方式)`。steer / follow_up 由 runner 在回合内排空;
+        #: next_turn 留到下一次用户输入(见 `_drain_messages` 与 `_stream_inner` 开头)。
+        self._pending_messages: dict[str, list[dict[str, Any]]] = {
+            "steer": [], "follow_up": [], "next_turn": []}
+        # 信任决定**只从用户级 settings 读**(`defaultProjectTrust`)。项目级那份不能自己声明
+        # “我可信”:否则仓库只要提交一行 `"defaultProjectTrust": "always"` 就能让自己的
+        # 任意代码跑起来 —— 而这正是这道门控要防的事(实测过:确实能跑)。
+        # pi 同模型:它的信任决定也存在用户 home 里(`trust.json`),不在仓库里。
+        scopes = load_settings_by_scope(self.cwd)
+        from .trust import TrustStore          # 局部导入:信任库只在构造时用一次
+
+        self.project_trusted, self.trust_reason = resolve_project_trust(
+            scopes.get("user"), approve=approve_project, has_ui=has_ui,
+            stored=TrustStore().get(self.cwd))
+        #: 信任是否已被**最终**定下(见 `_bind_project_trust`)。构造期那份可能是临时的。
+        self._trust_bound = False
+        #: 本会话里思考级别被**显式**设过吗(是 → 换模型不再按 `modelThinkingLevels` 覆盖)。
+        #: 记的是**会话 id** 而不是一个 bool:显式选择属于它被设的那个会话,否则 web 那种
+        #: "一个 runtime 服务多个会话"的场景里,在 A 上设一次之后切到 B 也还带着它
+        #: (A 的显式选择泄漏给了 B)。判断见 `_level_pinned()`。
+        self._level_pins: set[str] = set()
+        #: 思考级别被**命令行**钉住(`--thinking`,或 `--model p/m:级别`)—— 对所有会话生效。
+        #: 与 `_level_pins` 分开:那是会话级的,这个是**整场运行**的。
+        #: 命令行给的值是当次显式覆盖,不该被会话里记的旧值顶掉(与 `_model_pinned` 对称)。
+        self._level_pinned_cli = False
+        declared_by_repo = (getattr(scopes.get("project"), "defaultProjectTrust", None)
+                            or "").strip()
+        if declared_by_repo:
+            # 不静默:一个仓库自称可信是值得报警的事
+            self.notes.append(
+                f"项目 settings 里写了 defaultProjectTrust={declared_by_repo} —— **已忽略**:"
+                "信任决定不能由仓库自己声明(用 `qi -a`,或写进**用户级** settings)")
+        if not self.project_trusted and paths.project_extensions_dir(self.cwd).is_dir():
+            self.notes.append(
+                f"未信任项目({self.trust_reason}):`.qi/extensions/` 未加载;用 `qi -a` 信任")
+        legacy_ext = paths.legacy_project_extensions_dir(self.cwd)
+        if legacy_ext is not None:
+            self.notes.append(
+                f"检测到旧目录 `{legacy_ext.relative_to(self.cwd)}` —— 已改名为 "
+                f"`extensions/`,请手动改名(不会自动改仓库内容)")
+        # `ctx.ui`:前端(TUI)在构造时把自己的实现递进来;没有前端时它按调用方给的
+        # default 回答,所以 `-p` 不会卡在这里。notes 共用同一个列表 —— 无界面时
+        # `ui.notify` 落进来就自动变成启动提示。
+        #
+        # 为什么走构造参数而不是一个 `set_ui_frontend()`:后者多一个“别忘了调”的次序隐患,
+        # 而且每次给假运行时加方法都会撞一遍。
+        # (web 不行 —— 每个浏览器连接是一个不同的前端,那边要按回合解析,见 §5.1。)
+        #
+        # `mode` 是 pi 的 `ExtensionMode`(tui / rpc / json / print):组件层 ctx.ui
+        # 只在 tui 下有意义,扩展用 `ctx.mode` 做门控。不显式给就按 has_ui 推。
+        self.mode = mode or ("tui" if has_ui else "print")
+        self.ui = ExtensionUi(frontend=ui_frontend, notes=self.notes, mode=self.mode,
+                              bus=self.bus,
+                              ctx_factory=lambda signal=None: self.extension_ctx(signal))
+        #: 渲染回调登记处(`registerMessageRenderer` / `registerEntryRenderer` /
+        #: `registerMarkdownTransformer`)。前端按它决定怎么画 —— TUI-only。
+        self.renderers = RendererRegistry()
+        #: `resources_discover` 带给我们的提示词/主题路径(前端从这儿取)
+        self.extra_resource_paths: list[Path] = []
+        #: 正在跑回合吗(`ctx.isIdle()`)。由 `stream()` 的 wrapper 维护。
+        self._idle = True
+        #: 空闲等待用的信号(`ctx.waitForIdle()`)
+        self._idle_event = asyncio.Event()
+        self._idle_event.set()
+        #: 当前回合的中断信号(`ctx.abort()` 的回退路径)
+        self._abort_signal: AbortSignal | None = None
+        #: 最近一次建好的 system prompt(`ctx.getSystemPrompt()` 优先返回它)
+        self._last_system_prompt: str | None = None
+        #: 扩展请求“空闲时开一轮”的队列(`sendUserMessage(trigger_turn=True)`)。
+        #: 前端在本轮/命令处理完后用 `take_turn_request()` 领取。
+        self._turn_requests: list[str] = []
+        #: 前端注入的退出实现(`ctx.shutdown()`);没注入时是 no-op。
+        self._shutdown: Any = None
+        # 扩展命令/快捷键的汇合点(TUI 按它分发 `/cmd` 与按键)
+        self.commands = CommandRegistry()
+        # CLI 旗标(扩展用 `registerFlag` 声明;值走 core 的 `--ext name=value`)
+        self.flags = FlagRegistry()
+        #: `--ext` 里**不能用**的那些(名字打错 / 值非法)。与 `notes` 分开:
+        #: 这个是致命的(用户打错了命令行),CLI 据此退出码 2;notes 只是告知。
+        self.flag_errors: list[str] = []
+        # 附加扩展目录先算好:嵌在 kwargs 里会让这次调用看不出“传了哪几样”
+        if no_extensions:
+            # `--no-extensions`(pi):关掉**发现**(entry point / 内建目录 / settings),
+            # 但 `-e` 显式给的那些仍然加载
+            extra_extensions: list[Any] = list(extra_extension_paths or ())
+        else:
+            extra_extensions = extension_dirs(
+                self.cwd, trusted=self.project_trusted,
+                extra=list(extra_extension_paths or ()))
+        self.extensions = discover_extensions(
+            self.catalog, self.capabilities, self.cwd,
+            cli_commands=CliCommandRegistry(),
+            renderers=self.renderers,
+            bus=self.bus,
+            host=self,
+            commands=self.commands,
+            flags=self.flags,
+            on_warning=self.notes.append,
+            extra_dirs=extra_extensions,
+            project_trusted=self.project_trusted,
+            no_discovery=no_extensions)
+        # `--ext` 的值要在**扩展声明之后**才能解析(名字与类型都在那边),所以放在这里
+        for pair in extension_flags or ():
+            problem = self.flags.provide(str(pair))
+            if problem:
+                self.flag_errors.append(problem)
+        self.notes.extend(self.flags.problems)
+        # 有角色目录、但没装能读它的扩展 —— 这是最容易"文件在那里但毫无作用"的一种静默
+        self._note_missing_agent_support()
+
+        # 顶层技能(~/ .agents > qi 全局 > .agents 项目 > qi 项目 > settings)。
+        # v3:技能是 **core** 的能力(与角色无关),所以它直接进提示词,不再“随 agent 绑定”。
+        self.top_skills = load_top_level_skills(
+            self.cwd, self.settings,
+            list(extra_skill_paths or ()),
+            enabled=skills_enabled and self.settings.skillsEnabled,
+        )
+
+        auth: AuthStore = AuthOverride(api_key) if api_key else AuthStore()
+        #: 换模型时要重建客户端,所以凭证存储要留在身上(`set_model` 用)
+        self._auth = auth
+        if model_override:
+            # `--model`:`provider/模型[:思考级别]`(对齐 pi)
+            ref, _flag_thinking = parse_model_flag(model_override)
+            provider, _, model_name = ref.partition("/")
+            default: ResolvedModel = resolve_model(self.cfg, provider.strip(), model_name.strip())
+        else:
+            _flag_thinking = None
+            default = resolve_default_model(self.cfg, self.cwd)
+        # 思考级别:显式传参(CLI --thinking)> `--model` 的后缀 > settings.defaultThinkingLevel
+        # > `DEFAULT_THINKING_LEVEL`(pi 默认 medium)。四级优先(pi 的口径):`--thinking` >
+        # `--model provider/id:<级别>` > `modelThinkingLevels[该模型]` > `defaultThinkingLevel`。
+        level = (thinking_level if thinking_level is not None
+                 else _flag_thinking if _flag_thinking is not None
+                 else model_thinking_level(self.settings, default)
+                 or self.settings.defaultThinkingLevel
+                 or DEFAULT_THINKING_LEVEL)
+        self.thinking_level = normalize_thinking_level(level)
+        # 命令行给过级别(任一形式)→ 整场运行都不再从会话里还原级别:
+        # 它是**当次**的显式覆盖,与 `--model` 同级(见 `_restore_context_settings`)。
+        self._level_pinned_cli = thinking_level is not None or _flag_thinking is not None
+        self.llm_exec = llm or self._make_client(default)
+        #: 还原失败时的**退路**。`llm_exec` 是**可变**的(换模型会整个换掉它),
+        #: 而"会话里记的模型没能恢复"时不能只是记一句 note 就完事 —— 那会把它留在
+        #: **上一个会话**的模型上(web 那种一个 runtime 服务多个会话的场景里必然发生)。
+        #: 保留构造期这份,才谈得上"已用默认模型继续"。见 `_restore_context_settings`。
+        self._default_llm_exec = self.llm_exec
+        # CLI 的工具收窄(pi 的 `--tools` / `-xt` / `-nt` / `-nbt`)。
+        # 必须等扩展注册完(B)才能算 —— `--no-builtin-tools` 要知道每个工具的来源。
+        self._apply_tool_flags(tools=tools, exclude_tools=exclude_tools,
+                               no_tools=no_tools, no_builtin_tools=no_builtin_tools)
+
+    def _apply_tool_flags(self, *, tools: str | None, exclude_tools: str | None,
+                          no_tools: bool, no_builtin_tools: bool) -> None:
+        """把工具集来源落成一次"工具集覆盖"(对齐 pi 的口径)。
+
+        优先级照 pi(`docs/usage.md` 的旗标表 + `docs/settings.md` 的 `defaultTools` 段):
+        `--tools` 是**严格白名单**(替换默认集),`--no-tools` 全禁,`--no-builtin-tools`
+        只去内置;`--exclude-tools` **最后**过滤结果。`--tools` 与后两者矛盾,已在 CLI 拦住。
+
+        **没给任何 CLI 旗标**时才看 `settings.defaultTools`(pi 同名段):它只挑**内置**那一档,
+        扩展装的工具照旧全留 —— pi 的原话是 "An empty array starts with no built-in tools
+        while preserving extension/custom tools",所以 `defaultTools: []` 是个**有意义**的配置
+        (不要内置、只留扩展),不能与"没配"混为一谈(那是 `None`)。
+
+        未注册的工具名**不静默丢掉**:记一条 note(与 `api.setActiveTools` 同一口径)。
+        """
+        defaults = default_tools(self.settings)
+        if not any((tools, exclude_tools, no_tools, no_builtin_tools)):
+            if defaults is None:                 # 没配 → 不动覆盖(None ≠ 空集)
+                return
+            builtin = {n for n in self.catalog.names
+                       if tool_source(self.catalog, n) == "builtin"}
+            keep = set(defaults)
+            weird = sorted(keep - builtin)
+            if weird:
+                self.notes.append("settings.defaultTools 里有未注册的内置工具:"
+                                  + "、".join(weird))
+            chosen = sorted((set(self.catalog.names) - builtin) | (keep & builtin))
+            self.set_tool_names(chosen)
+            self.notes.append("本次运行的工具集(defaultTools):"
+                              + ("、".join(chosen) if chosen else "(空)"))
+            return
+        known = set(self.catalog.names)
+        unknown: list[str] = []
+        if tools:
+            wanted = split_tool_list(tools)
+            unknown += [n for n in wanted if n not in known]
+            chosen = [n for n in wanted if n in known]
+        elif no_tools:
+            chosen = []
+        elif no_builtin_tools:
+            chosen = sorted(n for n in known if tool_source(self.catalog, n) != "builtin")
+        else:
+            chosen = sorted(known)
+        if exclude_tools:
+            dropped = split_tool_list(exclude_tools)
+            unknown += [n for n in dropped if n not in known]
+            gone = set(dropped)
+            chosen = [n for n in chosen if n not in gone]
+        if unknown:
+            self.notes.append("工具旗标里有未注册的名字:" + "、".join(dict.fromkeys(unknown)))
+        self.set_tool_names(chosen)
+        self.notes.append("本次运行的工具集:" + ("、".join(chosen) if chosen else "(空)"))
+
+    # ── 工具上下文(每个会话独立) ──
+    def _has_agent_support(self) -> bool:
+        """这个运行里有没有「角色」这件事。
+
+        判据用**行为**而不是包名:qi-agents 的全部工作就是注册 `subagent` 工具,
+        而它的名字随安装通道而变(entry point 叫 `agents`、目录通道叫目录名)。
+        """
+        if "subagent" in self.catalog.names:
+            return True
+        return any(str(name).replace("_", "-") in {"agents", "qi-agents"}
+                   for name in (self.extensions or ()))
+
+    def _note_missing_agent_support(self) -> None:
+        """有角色目录、但没有能读它的扩展 → 说一句(否则那些文件静默无效)。
+
+        与 design/extensions-design.md 的迁移清单同源:`.qi/agents/` 归 qi-agents,
+        core 不读它。未信任的项目目录也有可能读不到 —— 但那种情况另有提示
+        (信任门控自己会说),这里只说"扩展不在"。
+        """
+        if self._has_agent_support():
+            return
+        roots = [paths.global_home() / paths.AGENTS_DIR_NAME,
+                 paths.project_home(self.cwd) / paths.AGENTS_DIR_NAME]
+        found = [root for root in roots
+                 if root.is_dir() and any(root.glob(f"*/{paths.AGENT_FILE_NAME}"))]
+        if not found:
+            return
+        listed = "、".join(str(root) for root in found)
+        self.notes.append(
+            f"检测到角色目录({listed})但没装读它的扩展:`qi-agents` 未加载 —— "
+            f"这些角色不会被使用(装法:`pip install qi-agents`,然后 `qi doctor` 确认)")
+
+    def _tool_ctx(self, agent_name: str) -> ToolContext:
+        """工具上下文。
+
+        v3 里没有 `data_sources` 了 —— 数据源实例住在 agent 目录里,而 agent 归 qi-agents
+        (E15/E18:它会把作用域交给提供该配置种类的扩展自己去读)。
+        """
+        return ToolContext(agent_name=agent_name, workdir=self.workdir,
+                           ask=self._ask,
+                           shell_path=self.settings.shellPath,
+                           project_trusted=self.project_trusted,
+                           ui=self.ui,
+                           session_env=self._session_env())
+
+    def _session_env(self) -> dict[str, str]:
+        """这一回合的会话环境变量(pi 的 `exposeSessionEnvironment`)。
+
+        取的是**绑定的会话 + 当前模型 + 当前级别** —— 与 `ctx.model` / `ctx.thinkingLevel`
+        同一份真实来源,所以 bash 里 `env | grep QI_` 得到的答案与 footer 显示的一致。
+        """
+        session = self.current_session()
+        view = self._model_view()
+        return session_env(
+            session_id=getattr(session, "id", None),
+            session_file=str(getattr(session, "path", "") or "") or None,
+            provider=getattr(view, "provider", None) if view is not None else None,
+            model=getattr(view, "id", None) if view is not None else None,
+            reasoning_level=self.thinking_level)
+
+    def _child_session_env(self, model_ref: Any) -> dict[str, str]:
+        """子运行的环境变量:模型按**子运行自己的**那个算,其余继承会话。
+
+        pi 的 `ctx.model` 在子运行里就是子运行的模型;若照抄父的 `QI_MODEL`,
+        子 agent 自查时会得到"我在用别的模型"这种假答案。
+        """
+        env = dict(self._session_env())
+        if not model_ref:
+            return env
+        provider, _, model_id = str(model_ref).partition("/")
+        if provider and model_id:
+            env["QI_PROVIDER"] = provider
+            env["QI_MODEL"] = model_id
+        return env
+
+    # ── 受管子运行(扩展的 `runAgent` / E12)──
+    def _make_client(self, resolved: ResolvedModel) -> LiteLLMClient:
+        """建 provider 客户端并接上**三件套事件**(唯一入口)。
+
+        三个调用点(默认客户端 / 换模型 / 子运行)共用同一份接线 —— 否则“某个路径上的
+        扩展看不到请求”会变成一种只在特定入口复现的鬼故事。
+        """
+        return LiteLLMClient(resolved, self._auth,
+                             thinking_level=self.thinking_level,
+                             retry=self.settings.retry,
+                             thinking_budgets=self.settings.thinkingBudgets,
+                             bus=self.bus,
+                             extension_ctx=lambda signal: self.extension_ctx(signal))
+
+    def _client_for(self, model_ref: str | None) -> Any:
+        """子运行用的客户端:给了 `"provider/model"` 就**另建一个**,不给就用当前的。
+
+        关键点:另建时**不碰** `self.llm_exec` —— 子运行换模型不应改变父会话的模型。
+        """
+        if not model_ref:
+            return self.llm_exec
+        provider, _, model = str(model_ref).partition("/")
+        if not model:
+            raise ValueError(f'模型要写成 "provider/model",收到 {model_ref!r}')
+        return self._make_client(resolve_model(self.cfg, provider, model))
+
+    async def run_agent(self, spec: Any, task: str, *, abort: AbortSignal | None = None,
+                        on_event: Any = None) -> str:
+        """在宿主内起一个**受管的子运行**(E12):独立上下文、自己的工具集与模型。
+
+        **与 `stream()` 的区别**(为什么不直接嵌套 stream):子运行**不碰会话** ——
+        不落盘、不派发、不改 active_agent。它是“借一次工具循环”,不是“再来一轮对话”。
+        所以它不会污染父会话的上下文,也不会在历史上多出几条看不懂的消息。
+
+        **但扩展事件照常派发**(用同一个总线与 ctx):所以权限闸门(`tool_call`)
+        对子运行一样生效 —— 这是“进程内”相对“子进程”的一个真实好处(子进程里宿主看不见)。
+
+        `spec` 是 dict:`system_prompt`(必填)/ `tools`(缺省**继承父**的当前集合,
+        而不是 catalog 全部 —— 给子运行比父多出权限是提权)/ `model`(缺省继承父)/ `name`。
+        递归深度由**扩展自己**管(E12):宿主不猜你允许多深。
+        """
+        data = spec if isinstance(spec, dict) else {
+            "system_prompt": getattr(spec, "prompt", ""),
+            "tools": getattr(spec, "tools", None),
+            "name": getattr(spec, "name", None)}
+        prompt = str(data.get("system_prompt") or "").strip()
+        if not prompt:
+            raise ValueError("runAgent 需要 system_prompt(子运行要有自己的提示词)")
+        tools = data.get("tools")
+        if tools is None:
+            tools = self.tool_names()          # 继承父的当前集合(不是 catalog 全部)
+        name = str(data.get("name") or "subagent")
+        run_spec = RunSpec(name=name, prompt=prompt, tools=[str(t) for t in tools])
+        ctx = ToolContext(agent_name=name, workdir=self.workdir, ask=self._ask,
+                          shell_path=self.settings.shellPath, ui=self.ui,
+                          project_trusted=self.project_trusted,
+                          session_env=self._child_session_env(data.get("model")),
+                          abort=abort)
+        runner = AgentRunner(run_spec, self.catalog, self._client_for(data.get("model")),
+                            tool_ctx=ctx,
+                            bus=self.bus,
+                            extension_ctx=lambda signal: self.extension_ctx(signal),
+                            report=self.notes.append)
+        final = ""
+        async for event in runner.run(task, abort=abort):
+            if event.kind == "agent_end":
+                final = event.text or final
+            if on_event is not None:
+                on_event(event)
+        return final
+
+    async def _ask(self, question: str) -> str | None:
+        """`clarify` 工具的交互入口。
+
+        有 UI 前端时走 `ctx.ui.input` —— 这修掉一个旧缺陷:`_ask` 以前无条件返回 None,
+        所以**内置的 clarify 在 TUI 里也从没问过人**(它一直只会说“无人可问”)。
+        没前端(无头/脚本)仍返回 None,保持“不吃 stdin”的行为。
+        """
+        if not self.ui.has_frontend:
+            return None
+        return await self.ui.input(question, title="澄清")
+
+    # ── 扩展上下文与事件 ──
+    def _model_label(self) -> str | None:
+        """`"provider/model"`;拿不到 spec 就 None。"""
+        view = self._model_view()
+        return str(view) if view is not None else None
+
+    def _model_view(self) -> ModelView | None:
+        """当前模型的 `ModelView`(pi 的 `ctx.model` 形状;`str` 子类所以旧用法不变)。"""
+        spec = getattr(self.llm_exec, "spec", None)
+        if spec is None:
+            return None
+        try:
+            return ModelView.from_resolved(spec)
+        except Exception:  # noqa: BLE001 第三方/测试替身可能不是 ResolvedModel
+            return None
+
+    def extension_ctx(self, signal: AbortSignal | None = None,
+                      session: Session | None = None) -> ExtensionContext:
+        """构造 handler 用的 `ctx`(§3.3 的最小集)。
+
+        **不是**缓存单例:每回合的信号不同(`signal`),而 ctx 冻结这些值。
+
+        `session` 缺省用回合绑定的那个(`_active_session`)—— 所以 runner 里的 handler
+        拿到的 `ctx.session_manager` 就是当前会话;回合外(如 TUI 命令)拿不到时
+        `available` 为 False、写口报错。
+        """
+        return ExtensionContext(
+            cwd=self.cwd,
+            model=self._model_view(),
+            thinking_level=self.thinking_level,
+            signal=signal,
+            has_ui=self._has_ui,
+            project_trusted=self.project_trusted,
+            notes=self.notes,
+            ui=self.ui,
+            mode=self.mode,
+            session=session if session is not None else self._active_session,
+            scoped_models=tuple(self.scoped_models or ()),
+            host=self,
+            model_registry=ModelRegistryView(self),
+            session_manager=SessionView(session if session is not None
+                                        else self._active_session),
+        )
+
+    # ── provider(扩展的 `registerProvider`)──
+    def register_provider(self, name: str, config: dict, source: str) -> None:
+        """动态注册/覆盖一个 provider。**只改内存里的 cfg,不写 `models.json`。**
+
+        写盘会让“跑一次带代理的扩展”永久改变用户的模型配置 —— 而那是个静默的副作用。
+        所以扩展注册的 provider 只活在这个进程里(pi 允许扩展持久化目录元数据、
+        带 generation 校验 —— 那是另一套机制,qi 没做)。
+        """
+        if name in self.cfg.providers:
+            self.notes.append(f"扩展 {source} 覆盖了已有的 provider {name}")
+        try:
+            self.cfg.providers[name] = ProviderConfig.model_validate(config)
+        except Exception as exc:  # noqa: BLE001 pydantic 校验错
+            raise ValueError(f"provider {name} 配置不合法: {exc}") from exc
+
+    def append_extension_entry(self, custom_type: str, data: dict, source: str) -> None:
+        """扩展自定义 entry 的**唯一写口**(`api.appendEntry` 走这里)。
+
+        章由宿主盖:`source`(哪个扩展写的)、`agent`(当时哪个角色在跑)。扩展自己拼 entry
+        的话迟早会出现两种形状,而回放/诊断都得同时认两种。
+
+        没有活动会话时**报错** —— 回合外的写往往是“想存但存错地方”的第一步。
+        """
+        session = self._active_session
+        if session is None:
+            raise RuntimeError("没有活动会话:appendEntry 只能在回合内调用")
+        self.sessions.append(session, {
+            "type": "custom", "custom_type": custom_type,
+            "source": source, "agent": CORE_AGENT_NAME,
+            "data": data})
+
+    def queue_extension_message(self, text: str, deliver_as: str, source: str,
+                                kind: str = "sendMessage", *, custom_type: Any = None,
+                                display: Any = None, details: Any = None,
+                                trigger_turn: bool = False) -> None:
+        """扩展消息的唯一入队口(`api.send_message` / `send_user_message` 走这里)。
+
+        **不在这里落盘**:送达时机在 runner 手里(每次 LLM 调用前 / 本该收工时 / 下次输入),
+        而“什么时候进对话”与“什么时候进文件”必须是同一个时刻 —— 先落盘会让历史里出现一条
+        还没送达的消息。落盘在 `_drain_messages` 里做,与排空同时。
+
+        `trigger_turn` 且此刻**空闲**时走另一条路:不当成排队消息,而是记一条“该开一轮了”
+        的请求(`take_turn_request()`),由前续流程开一轮 —— pi 的 `triggerTurn` 就是这个语义。
+        """
+        if trigger_turn and self._idle:
+            self._turn_requests.append(text)
+            return
+        bucket = self._pending_messages.get(deliver_as)
+        if bucket is None:                       # `api` 侧已经挡过,这里只是双保险
+            raise ValueError(f"未知的 deliver_as: {deliver_as!r}")
+        bucket.append({"text": text, "source": source, "kind": kind,
+                       "custom_type": custom_type, "display": display,
+                       "details": details})
+
+    def take_turn_request(self) -> str | None:
+        """取一条“扩展要求开一轮”的请求(没有则 None)。前端在空闲时调用。"""
+        return self._turn_requests.pop(0) if self._turn_requests else None
+
+    def _drain_messages(self, deliver_as: str) -> list[str]:
+        """排空某一档的待发消息,**同时落盘**。
+
+        落盘放这里而不是 runner 里:runner 不认识会话(它的 `msgs` 是本地上下文表),
+        而“谁负责落盘”只有一个答案才是稳的。
+
+        回合外(`_active_session` 为空)只排空不落盘 —— 那种情况只可能是 next_turn
+        在输入之前被取走,而它本来就还没进对话。
+        """
+        bucket = self._pending_messages.get(deliver_as) or []
+        if not bucket:
+            return []
+        texts = [str(item.get("text") or "") for item in bucket]
+        session = self._active_session
+        if session is not None:
+            for item in bucket:
+                entry: dict = {"type": "message", "role": "user",
+                               "content": item.get("text") or "",
+                               "agent_id": CORE_AGENT_NAME,
+                               "injected_by": item.get("kind"),
+                               "deliver_as": deliver_as, "source": item.get("source")}
+                # pi 的 `sendMessage({customType, display, details})`:进上下文的同时
+                # 带上由前端决定怎么画的元数据(customType 进 custom_type,同 qi 既有键名)
+                if item.get("custom_type"):
+                    entry["custom_type"] = item["custom_type"]
+                if item.get("display") is not None:
+                    entry["display"] = item["display"]
+                if item.get("details") is not None:
+                    entry["details"] = item["details"]
+                self.sessions.append(session, entry)
+        bucket.clear()
+        return texts
+
+    async def _bind_project_trust(self) -> None:
+        """定信任(可被 `project_trust` 事件改),并按最终决定补装**项目级**扩展。
+
+        为什么信任判定要推迟到这里:pi 的 `project_trust` 事件是 **async** 的(扩展可以投票),
+        而构造期没有事件循环 —— TUI 在 `on_mount` 里构造 runtime(`tui.py`),那里已经在 loop 中,
+        `asyncio.run` 会直接抛 "cannot be called from a running event loop"(实测)。
+
+        所以构造期先按 **fail-closed** 装完:用户级目录与 entry point 与项目信任无关,先装好正好
+        让它们能在事件里投票 —— pi 的语义正是"只有用户级/CLI 扩展拥有投票权"。项目级那一半等
+        决定下来再补(见 `_load_project_extensions`)。
+
+        幂等;`-a` / `-na` 给过就**不发事件**(用户当场的指令优先)。
+        """
+        if self._trust_bound:
+            return
+        self._trust_bound = True
+        if self._approve_flag is not None or not self.bus.has("project_trust"):
+            return
+        result = await self.bus.emit_until(
+            "project_trust",
+            {"cwd": str(self.cwd), "has_ui": self._has_ui},
+            ctx=self.extension_ctx(),
+            # pi 的契约:`{trusted: "yes" | "no" | "undecided"}`,**首个 yes/no 拥有决定权**,
+            # `undecided` 继续往下走(所以 stop_values 按"键 → 取值集合"给)。
+            stop_values={"trusted": ("yes", "no")})
+        for source, exc in result.errors:
+            self.notes.append(f"扩展 {source} 的 project_trust 处理失败: {exc}")
+        verdict = str(result.payload.get("trusted") or "").strip().lower()
+        if verdict not in ("yes", "no"):
+            return                      # 没人下结论 → 构造期那份就是最终决定
+        decided = verdict == "yes"
+        if bool(result.payload.get("remember")):
+            # pi 的 `remember: true` → 落盘(下次启动直接用它,不再问)
+            try:
+                from .trust import TrustStore
+
+                TrustStore().set(self.cwd, decided)
+                self.notes.append("信任决定已记住(trust.json)")
+            except OSError as exc:
+                self.notes.append(f"信任决定没能记住: {exc}")
+        if decided == self.project_trusted:
+            self.trust_reason = f"扩展决定了{'信任' if decided else '不信任'}"
+            return
+        self.project_trusted = decided
+        self.trust_reason = f"扩展决定了{'信任' if decided else '不信任'}"
+        if decided:
+            # 只有"不信任 → 信任"需要动作;反方向不用做事 —— 构造期本来就是 fail-closed
+            # (一个项目级的扩展、配置都没装)。
+            self._load_project_extensions()
+
+    def _load_project_extensions(self) -> None:
+        """第二趟:只装**项目级**(构造期按 fail-closed 跳过的那半)。
+
+        为什么只装项目级:用户目录与 entry point 第一趟已经装过,再来一遍会撞 catalog 的
+        "工具重复注册"。`extension_dirs(trusted=True)` 里筛出 project 作用域的那些即可 ——
+        它们正是第一趟因为不信任而没拿到的。
+        """
+        extra = [item for item in extension_dirs(
+            self.cwd, trusted=True, extra=self._extra_extension_paths)
+            if item[1] == "project"]
+        loaded = discover_extensions(
+            self.catalog, self.capabilities, self.cwd,
+            cli_commands=CliCommandRegistry(),
+            renderers=self.renderers,
+            bus=self.bus, host=self, commands=self.commands, flags=self.flags,
+            on_warning=self.notes.append,
+            extra_dirs=extra, project_trusted=True, only_project=True)
+        self.extensions.extend(loaded)
+        self.notes.append("信任由扩展决定:已加载项目级扩展"
+                          + (f"({len(loaded)} 个)" if loaded else ""))
+
+    async def start_session(self, session: Session, reason: str = "startup") -> None:
+        """告知扩展"会话已绑定"(pi 的 `session_start { reason }`)。
+
+        **幂等**:同一 runtime 对同一会话只派发一次。前端可能会在多个时机绑定同一会话,
+        重复派发会把扩展的"开一次资源"变成开 N 次 —— 宿主自己记账,扩展不必防重。
+
+        handler 抛异常不往外传(§4 规则 3):记进 `notes`,会话照跑。扩展坏在启动时,
+        用户至少能在界面上看到一行字,而不是"啥都没发生"。
+        """
+        # 信任必须在**任何**项目级资源被用到之前定下(零扩展时也照样要做)。
+        await self._bind_project_trust()
+        # 会话设置(模型 / 思考级别)在**通知扩展之前**定下来:扩展在 `session_start`
+        # 里就会读 `ctx.model` / `ctx.thinkingLevel`,那时必须已经是这个会话的值。
+        self.bind_session(session)
+        if session.id in self._started_sessions:
+            return
+        self._started_sessions.add(session.id)
+        if self.bus.is_empty:
+            return
+        event = await self.bus.emit(
+            "session_start",
+            {"reason": reason, "session": session.id, "cwd": str(self.cwd)},
+            ctx=self.extension_ctx())
+        for source, exc in event.errors:
+            self.notes.append(f"扩展 {source} 的 session_start 处理失败: {exc}")
+        # pi 在 `session_start` **之后**再发 `resources_discover`:扩展这时可以补技能/
+        # 提示词/主题路径。reason 只有 startup / reload 两个取值(pi 同形)。
+        await self._emit_resources_discover(
+            reason="reload" if reason == "reload" else "startup")
+
+    # ── 工具集(扩展 `setActiveTools` / `getActiveTools` 的后端)──
+    def tool_names(self) -> list[str]:
+        """本回合实际启用的工具名。
+
+        覆盖(`setActiveTools`)优先;没有覆盖时就是 catalog 里的全部。
+        v3 里 agent 不再声明 `tools`(角色归 qi-agents),所以这里不再需要 unit 参数 ——
+        需要收窄的场景就是 `setActiveTools`,那一条路径已经独立。
+        覆盖里已经不在 catalog 的名字会被滤掉(`setActiveTools` 允许先写名字、
+        工具随后才注册)。
+        """
+        if self._tool_override is not None:
+            return [n for n in sorted(self._tool_override) if n in self.catalog.names]
+        return sorted(self.catalog.names)
+
+    def set_tool_names(self, names: Iterable[str]) -> None:
+        """覆盖工具集(扩展走的入口是 `api.setActiveTools`),对**后续回合**生效。"""
+        self._tool_override = set(names)
+
+    # ── 会话绑定(设置类 entry 要写进哪个文件)──
+    def bind_session(self, session: Session | None) -> None:
+        """把「当前会话」定下来(前端选完会话就调一次)。
+
+        为什么要有它:`_active_session` 只在**一个回合内**有效(`stream()` 里设、
+        `finally` 里清),而换模型 / 换思考级别是回合外发生的 —— TUI 的 `/model`
+        在两次提问之间、扩展在自己的 handler 里都可能调。那时若没有绑定会话,
+        `model_change` 就不知道该写进哪个文件(pi 的 `sessionManager` 是常驻的,
+        qi 这一层以前不存在,所以补一个**显式**的绑定,而不是去猜)。
+
+        传 `None` 解绑(会话被删掉时用)。绑定同时把会话里记的模型/级别恢复过来 ——
+        与 pi 一样:**先看会话记了什么**,没有再退回 settings 默认。
+
+        **绑的会话换了才还原**(见 `_restored_session`):同级重绑(web 每回合开跑前
+        都会调一次)不重复还原,而 A → B → A 切回来会 —— 后者以前不还原,于是
+        "切回 A 却还拿着 B 的模型"。
+        """
+        self._bound_session = session
+        if session is not None and session.id != self._restored_session:
+            self._restored_session = session.id
+            self._restore_context_settings(session)
+
+    def _level_pinned(self) -> bool:
+        """本回合的思考级别是否被**显式**设过(命令行 / 本会话里的 `/thinking`)。
+
+        命令行那档对所有会话生效;会话那档只认**当前绑定的这个会话** ——
+        否则"在 A 上设过"会泄漏到 B(见 `_level_pins`)。
+        """
+        if self._level_pinned_cli:
+            return True
+        session = self.current_session()
+        return session is not None and session.id in self._level_pins
+
+    def current_session(self) -> Session | None:
+        """当前会话:回合内用回合绑定的那个,否则用前端绑定的那个。"""
+        return self._active_session or self._bound_session
+
+    def _restore_context_settings(self, session: Session) -> None:
+        """按会话里记的设置类 entry 还原模型与思考级别(pi 的 `getSessionContextSettings`)。
+
+        命令行显式给过(`--model` / `--thinking`)就不还原 —— 那是有意的当次覆盖,
+        不该被历史里的旧值顶掉。
+
+        解析不出来的模型(provider 已删、凭证没了)**退回默认并记一条 note**:
+        静默用默认值会让人以为"切换没生效",而直接报错会让会话打不开 —— pi 的
+        `Could not restore model …` 也是这个取舍。
+        """
+        branch = session.branch()
+        if not branch:
+            # 新会话/空会话:没有历史可还原,把**当前**设置记成这个会话的起点
+            self._record_model_change(session)
+            self._record_thinking_change(session)
+            return
+        saved = context_settings(branch)
+        # **先看凭证**:provider 还在配置里、但密钥已经被删/没登录 —— 这时若照样还原,
+        # 用户会得到"一次注定 401 的请求",而按 pi 的口径(`hasConfiguredAuth`)应当
+        # 退回一个能用的模型。
+        #
+        # 判据用 `resolve_key(...).ok` 而不是 `has_configured_auth`:后者按 qi 的"预置
+        # 兜底"口径认**约定环境变量**(provider 名 → `DEFAULT_API_KEY_ENV`),比这里要的
+        # 严松度更宽 —— 沿用会话时"能不能真的拿到 key"才是那个问题。
+        resolved = None
+        if not self._model_pinned and saved["model"] is not None:
+            provider, model_id = saved["model"]
+            reason = ""
+            try:
+                candidate = resolve_model(self.cfg, provider, model_id)
+            except Exception as exc:  # noqa: BLE001 配置问题不该让会话打不开
+                reason = str(exc)
+            else:
+                key = resolve_key(candidate.provider, candidate.api_key_ref, self._auth)
+                if key.ok:
+                    resolved = candidate
+                else:
+                    reason = key.source or "没有可用密钥"
+            if resolved is not None:
+                self.llm_exec = self._make_client(resolved)
+            else:
+                # **真的退回默认**,而不是只记一句 note:此刻 `llm_exec` 可能还是
+                # **上一个会话**的模型(web:一个 runtime 服务多个会话),留在那里
+                # 就会拿别人的模型跑,而提示词里还写着"已用默认模型继续" —— 那是谎话。
+                self.llm_exec = self._default_llm_exec
+                self.notes.append(
+                    f"会话里记的模型 {provider}/{model_id} 没能恢复({reason});"
+                    "已用默认模型继续")
+        level = saved["thinking_level"]
+        if level is None:
+            # 老会话(这个字段上线前建的):补一条,避免它每次都被当"没记过"
+            self._record_thinking_change(session)
+        elif not self._level_pinned_cli:
+            # **只尊重命令行那档**:会话里记的级别**就是**用户在这个会话上显式选的那个
+            # (`set_thinking_level` 落的就是这条 entry),所以还原它不是在"覆盖用户的选择",
+            # 而是在把它装回来。会话级的 `_level_pins` 只用在一处 —— `set_model` 的
+            # 自动联动(`modelThinkingLevels` 不该覆盖显式选择)—— 不要在这里也用它,
+            # 否则"A 上设过 high"会让之后切回 A 读到的还是 B 的 low。
+            self.thinking_level = normalize_thinking_level(level)
+            client = getattr(self, "llm_exec", None)
+            if isinstance(client, ThinkingLLMClient):
+                client.thinking_level = self.thinking_level
+
+    def _record_model_change(self, session: Session | None = None) -> bool:
+        """落一条 `model_change`(pi 的 `appendModelChange`)。返回是否真写了。"""
+        target = session if session is not None else self.current_session()
+        spec = getattr(getattr(self, "llm_exec", None), "spec", None)
+        if target is None or spec is None:
+            return False
+        try:
+            return self.sessions.set_context_setting(
+                target, MODEL_CHANGE,
+                {"provider": str(spec.provider), "model_id": str(spec.model)})
+        except OSError as exc:      # 写盘失败不该把一次切换搞垮(与 `set_session_title` 同形)
+            self.notes.append(f"模型切换没能记进会话文件: {exc}")
+            return False
+
+    def _record_thinking_change(self, session: Session | None = None,
+                                level: str | None = None) -> bool:
+        """落一条 `thinking_level_change`(pi 的 `appendThinkingLevelChange`)。"""
+        target = session if session is not None else self.current_session()
+        if target is None:
+            return False
+        value = normalize_thinking_level(level if level is not None else self.thinking_level)
+        try:
+            return self.sessions.set_context_setting(
+                target, THINKING_LEVEL_CHANGE, {"thinking_level": value})
+        except OSError as exc:
+            self.notes.append(f"思考级别没能记进会话文件: {exc}")
+            return False
+
+    # ── 模型与思考级别(扩展的 `setModel` / `setThinkingLevel` 走这里)──
+    def set_model(self, provider: str, model: str, *, source: str = "set") -> ResolvedModel:
+        """运行期换模型(**下一回合**生效)。返回解析后的模型(前端要拿它刷新显示)。
+
+        **唯一的换模型入口** —— UI(TUI 的 `/model`、Ctrl+P)与扩展(`api.setModel`)共用,
+        所以 `model_select` 只从这一处发:两个入口各自发事件,迟早一个漏发或多发。
+
+        重建客户端时**必须带上当前 `thinking_level` 与 `retry`**:否则切模型会默默丢掉它们
+        (footer 显示 high、请求里却没有 —— 这类表现最难查)。
+        """
+        resolved = resolve_model(self.cfg, provider, model)
+        # 换到那个模型时,**按模型配的档自动生效** —— 但要在重建客户端**之前**改,
+        # 否则客户端拿着旧级别(footer 显示 high、请求里却没有,这类最难查)。
+        # 本会话里被显式设过(`/thinking` / shift+tab / `api.setThinkingLevel`)就不再覆盖:
+        # 显式选择 > 配置。
+        tuned = model_thinking_level(self.settings, resolved)
+        if tuned is not None and not self._level_pinned():
+            adopted = normalize_thinking_level(tuned)
+            if adopted != self.thinking_level:
+                self.thinking_level = adopted
+                self._emit_notice("thinking_level_select", {
+                    "level": adopted, "previous_level": None, "source": "auto"})
+                # 换模型带来的级别变化也要落 entry(pi:它走的是同一个 `setThinkingLevel`)
+                self._record_thinking_change(level=adopted)
+        previous = getattr(getattr(self, "llm_exec", None), "spec", None)
+        self.llm_exec = self._make_client(resolved)
+        # 落一条 `model_change`:时间线上留下切换点,并且**续会话时按它还原**
+        # (pi 的 `appendModelChange` 就在这个位置)。回合外切换也能写 —— 靠 `bind_session`。
+        self._record_model_change()
+        self._emit_notice("model_select", {
+            "model": f"{resolved.provider}/{resolved.model}",
+            "previous": (f"{previous.provider}/{previous.model}" if previous else None),
+            "source": source})
+        return resolved
+
+    def reload_credentials(self) -> bool:
+        """重新解析凭证并重建客户端(登录 / 退出登录 / 换了 key 之后调)。
+
+        为什么必须有:`LiteLLMClient` 在**构造时**就把 key 解析好了(`self._resolved`),
+        所以写完 `auth.json` 不重建,用户以为登上了、请求还是拿旧 key 去 401。
+
+        返回是否真重建了(没有客户端时 False)—— 调用方据此决定要不要提“下一回合生效”。
+        """
+        spec = getattr(getattr(self, "llm_exec", None), "spec", None)
+        if spec is None:
+            return False
+        self.llm_exec = self._make_client(spec)
+        return True
+
+    def set_thinking_level(self, level: str, *, source: str = "set") -> str:
+        """改思考级别(下一回合生效)。返回归一后的级别。
+
+        `source` 只进事件 payload("set" = 显式设、"cycle" = shift+tab 轮转)。
+        """
+        previous = self.thinking_level
+        self.thinking_level = normalize_thinking_level(level)
+        client = getattr(self, "llm_exec", None)
+        # 可选能力:测试替身 / 第三方实现可能连 `thinking_level` 都没有
+        if client is not None and isinstance(client, ThinkingLLMClient):
+            client.thinking_level = self.thinking_level
+        self._emit_notice("thinking_level_select", {
+            "level": self.thinking_level, "previous_level": previous, "source": source})
+        # 记在**当前会话**上(没有会话就退回命令行那一档的语义:本次运行有效)——
+        # 这样"在 A 上设过"不会泄漏到 B(见 `_level_pinned`)。
+        session = self.current_session()
+        if session is not None:
+            self._level_pins.add(session.id)
+        else:
+            self._level_pinned_cli = True
+        # 与 `set_model` 对称:只在级别**真的变了**时才落 entry(pi 的 `isChanging`)
+        if previous != self.thinking_level:
+            self._record_thinking_change()
+        return self.thinking_level
+
+    def set_session_title(self, session: Session, title: str, *, source: str = "auto") -> None:
+        """改会话显示名(落盘 + 发 `session_info_changed`)。
+
+        标题有两条来源:自动命名(`source="auto"`)与用户 `/name`(`source="user"`)。
+        集中到这一处是为了**事件只发一次**,而且“空标题不覆盖”那条规则只写一遍。
+        """
+        cleaned = (title or "").strip()
+        if not cleaned:
+            return
+        try:
+            self.sessions.set_title(session, cleaned)
+        except OSError:
+            # 落盘失败不该把这一轮搞垮(与本仓其它“不因此中断主流程”的 except 同形)
+            return
+        self._emit_notice("session_info_changed", {"name": cleaned, "source": source})
+
+    # ── 扩展宿主面(ctx 上的方法回向这里)────────────────────────────
+    #
+    # 这一整块是 pi 的 `ExtensionContext` / `ExtensionCommandContext` 对应物的后端。
+    # `ctx` 是 frozen 的只读值,要问运行时的事就走这些方法。
+    def is_idle(self) -> bool:
+        """agent 空闲吗(没在流式)。"""
+        return self._idle
+
+    def abort(self) -> None:
+        """中断当前回合(`ctx.abort()`);没有回合在跑时 no-op。"""
+        if self._abort_signal is not None:
+            self._abort_signal.abort()
+
+    def has_pending_messages(self) -> bool:
+        """有没有排队等送达的扩展消息 / 待开一轮的请求。"""
+        return (any(self._pending_messages.values())
+                or bool(self._turn_requests))
+
+    def set_shutdown_hook(self, fn: Any) -> None:
+        """前端注入退出实现(`ctx.shutdown()` 走它)。"""
+        self._shutdown = fn
+
+    def shutdown(self) -> None:
+        """优雅退出(pi 的 `ctx.shutdown()`)。没注入实现时记一条 note。"""
+        if callable(self._shutdown):
+            self._shutdown()
+            return
+        self.notes.append("ctx.shutdown():没有前端注入退出实现,已忽略")
+
+    def context_usage(self) -> dict | None:
+        """当前上下文占用(pi 的 `ContextUsage`:`{tokens, contextWindow, percent}`)。"""
+        window = self._context_window()
+        if window <= 0:
+            return None
+        session = self._active_session
+        tokens = messages_tokens(self._history(session)) if session is not None else 0
+        return {"tokens": tokens, "contextWindow": window, "context_window": window,
+                "percent": (round(tokens / window * 100, 1) if window else None)}
+
+    def compact(self, options: dict | None = None) -> None:
+        """触发一次压缩,**不等**它跑完(pi 的 `ctx.compact()` 同语义)。"""
+        session = self._active_session
+        if session is None:
+            self.notes.append("ctx.compact():回合外没有会话,已忽略")
+            return
+        options = options or {}
+        instructions = str(options.get("customInstructions")
+                           or options.get("custom_instructions") or "") or None
+
+        async def _run() -> None:
+            try:
+                await self.compact_session(session, instructions)
+            except Exception as exc:  # noqa: BLE001 后台任务里的失败要看得见
+                self.notes.append(f"扩展触发的压缩失败: {exc}")
+
+        try:
+            asyncio.get_running_loop().create_task(_run())
+        except RuntimeError:
+            return
+
+    def current_system_prompt(self) -> str:
+        """当前生效的 system prompt(TUI 的 `/sysprompt`、扩展的 `ctx.getSystemPrompt()`)。
+
+        优先给**本回合实际建好的那一份**(扩展的 `before_agent_start` 改过),没跑过回合时
+        现算一份 —— 否则“读系统提示词”会得到一个与模型看到的不一样的东西。
+        """
+        if self._last_system_prompt is not None:
+            return self._last_system_prompt
+        return build_system_prompt(self.base_prompt, cwd=self.workdir,
+                                   tools=self.catalog.resolve(self.tool_names()),
+                                   skills=self.top_skills,
+                                   append=self.append_system_prompt,
+                                   context_files=[] if self._no_context_files else None)
+
+    def system_prompt_options(self) -> dict:
+        """造 system prompt 用的结构化选项(pi 的 `BuildSystemPromptOptions` 对应物)。"""
+        return {"cwd": str(self.workdir),
+                "tools": self.tool_names(),
+                "skills": [getattr(s, "name", str(s)) for s in self.top_skills],
+                "append_system_prompt": self.append_system_prompt,
+                "context_files": [] if self._no_context_files else None,
+                "base_prompt_source": self.base_prompt_source,
+                "agent": CORE_AGENT_NAME}
+
+    async def wait_for_idle(self) -> None:
+        """等当前回合跑完(pi 的 `ctx.waitForIdle()`)。"""
+        await self._idle_event.wait()
+
+    # ── 会话名与 label ──
+    def set_session_name(self, name: str) -> None:
+        """改当前会话名(`api.set_session_name` 走这里)。"""
+        session = self._active_session
+        if session is None:
+            raise RuntimeError("没有活动会话:set_session_name 只能在绑定会话后调用")
+        self.set_session_title(session, name, source="extension")
+
+    def get_session_name(self) -> str | None:
+        session = self._active_session
+        return (session.title or None) if session is not None else None
+
+    def set_entry_label(self, entry_id: str, label: str | None) -> None:
+        """给某条 entry 打/清 label(label entry 盖在 `targetId` 上,pi 同形)。"""
+        session = self._active_session
+        if session is None:
+            raise RuntimeError("没有活动会话:set_label 只能在回合内调用")
+        self.sessions.append(session, {"type": "label", "targetId": entry_id,
+                                       "label": label})
+
+    # ── 模型与 provider ──
+    def set_extension_model(self, model: Any) -> bool:
+        """扩展切模型(`api.set_model` 走这里)。接受 `"provider/model"` / `ModelView` /
+        `{provider, id}`。解析/鉴权失败只记 note 并返回 False(不把扩展的回合打断)。"""
+        provider = model_id = None
+        if isinstance(model, str):
+            provider, _, model_id = model.partition("/")
+        elif isinstance(model, dict):
+            provider = model.get("provider")
+            model_id = model.get("id") or model.get("model")
+        else:
+            provider = getattr(model, "provider", None)
+            model_id = getattr(model, "id", None)
+        if not provider or not model_id:
+            raise ValueError("set_model 需要 'provider/model'、ModelView 或 {provider, id}")
+        try:
+            self.set_model(str(provider), str(model_id), source="extension")
+        except Exception as exc:  # noqa: BLE001 未登记的模型 / 配置错
+            self.notes.append(f"扩展切模型失败({provider}/{model_id}): {exc}")
+            return False
+        return True
+
+    def unregister_provider(self, name: str) -> None:
+        """注销先前注册的 provider(pi 的 `unregisterProvider`)。找不到则 no-op。"""
+        if self.cfg.providers.pop(name, None) is None:
+            return
+        self.notes.append(f"扩展注销了 provider {name}")
+
+    def model_catalog(self) -> list[ModelView]:
+        """配置里**全部**模型(`ctx.model_registry.get_all()`)。"""
+        out: list[ModelView] = []
+        for provider, prov in (self.cfg.providers or {}).items():
+            for entry in (prov.models or []):
+                out.append(ModelView(provider, entry.id,
+                                     api=entry.api or prov.api or "",
+                                     base_url=prov.baseUrl,
+                                     reasoning=bool(entry.reasoning),
+                                     context_window=_as_int(entry.contextWindow),
+                                     max_tokens=_as_int(entry.maxTokens),
+                                     name=entry.name or entry.id))
+        return out
+
+    def available_models(self) -> list[ModelView]:
+        """能用的模型(当前口径与 `model_catalog()` 一致 —— qi 不做逐模型鉴权过滤)。"""
+        return self.model_catalog()
+
+    def has_configured_auth(self, model: Any) -> bool:
+        """这个模型的 provider 有凭据吗(配置里的 apiKey 或凭证库)。"""
+        provider = getattr(model, "provider", None) or (
+            model.get("provider") if isinstance(model, dict) else None)
+        if not provider:
+            return False
+        prov = (self.cfg.providers or {}).get(str(provider))
+        if prov is not None and prov.apiKey:
+            return True
+        try:
+            return self._auth.get(str(provider)) is not None
+        except Exception:  # noqa: BLE001 凭证库读失败不该把只读查询搞崩
+            return False
+
+    def provider_display_name(self, provider: str) -> str:
+        """provider 的展示名(没配就回落到名字本身,pi 同义)。"""
+        prov = (self.cfg.providers or {}).get(str(provider))
+        name = getattr(prov, "name", None) if prov is not None else None
+        return str(name) if name else str(provider)
+
+    # ── 会话操作(pi 的 ExtensionCommandContext)────────────────────────
+    async def _session_gate(self, event: str, payload: dict, ctx: Any) -> dict | None:
+        """发一个**可取消**的会话事件。返回那个裁决 dict(None = 没人拦)。"""
+        if not self.bus.has(event):
+            return None
+        result = await self.bus.emit_until(event, payload,
+                                           ctx=ctx or self.extension_ctx(),
+                                           stop_keys=("cancel",))
+        for src, exc in result.errors:
+            self.notes.append(f"扩展 {src} 的 {event} 处理失败: {exc}")
+        return result.result
+
+    async def extension_new_session(self, ctx: Any = None,
+                                    options: dict | None = None) -> dict:
+        """开一个新会话(`ctx.new_session()` 走这里)。"""
+        verdict = await self._session_gate("session_before_switch", {"reason": "new"}, ctx)
+        if verdict and verdict.get("cancel"):
+            return {"cancelled": True}
+        previous = self._active_session
+        if previous is not None:
+            await self.emit_session_shutdown("new")
+        session = self.sessions.create("", cwd=self.cwd)
+        self._active_session = session
+        await self.start_session(session, reason="new")
+        return {"cancelled": False, "session": session}
+
+    async def extension_fork(self, ctx: Any, entry_id: str,
+                             options: dict | None = None) -> dict:
+        """从某条 entry fork 出新会话(`ctx.fork()` 走这里;不传 entry_id 则空历史)。"""
+        source = self._active_session
+        if source is None:
+            raise RuntimeError("没有活动会话:fork 需要先绑定会话")
+        verdict = await self._session_gate(
+            "session_before_fork", {"entryId": entry_id}, ctx)
+        if verdict and verdict.get("cancel"):
+            return {"cancelled": True}
+        new = self.sessions.fork_at(source, entry_id)
+        self._active_session = new
+        await self.start_session(new, reason="fork")
+        return {"cancelled": False, "session": new}
+
+    async def extension_navigate_tree(self, ctx: Any, target_id: str,
+                                      options: dict | None = None) -> dict:
+        """把当前节点移到会话树里的另一处(`ctx.navigate_tree()`)。"""
+        session = self._active_session
+        if session is None:
+            raise RuntimeError("没有活动会话:navigate_tree 需要先绑定会话")
+        verdict = await self._session_gate(
+            "session_before_tree", {"targetId": target_id}, ctx)
+        if verdict and verdict.get("cancel"):
+            return {"cancelled": True}
+        if not self.sessions.set_position(session, target_id):
+            return {"cancelled": True, "error": f"未知的 entry: {target_id}"}
+        self._emit_notice("session_tree", {"newLeafId": target_id})
+        return {"cancelled": False, "session": session}
+
+    async def extension_switch_session(self, ctx: Any, session_path: str,
+                                       options: dict | None = None) -> dict:
+        """切到另一个会话文件(`ctx.switch_session()`)。"""
+        verdict = await self._session_gate(
+            "session_before_switch", {"reason": "resume", "targetSessionFile": session_path},
+            ctx)
+        if verdict and verdict.get("cancel"):
+            return {"cancelled": True}
+        session = self.sessions.open_file(session_path)
+        if session is None:
+            return {"cancelled": True, "error": f"打不开会话文件: {session_path}"}
+        await self.emit_session_shutdown("resume")
+        self._active_session = session
+        await self.start_session(session, reason="resume")
+        return {"cancelled": False, "session": session}
+
+    async def reload(self) -> None:
+        """重载资源与提示词(pi 的 `ctx.reload()` 的 qi 版)。
+
+        **不重新 import 扩展模块**(Python 不保证能安全重载:模块级状态、已注册的
+        工具/命令都可能重复)—— 重扫的是技能/基座提示词这类**资源**,并重发
+        `resources_discover` 与 `session_start(reason="reload")` 让扩展自己刷新。
+        """
+        self.base_prompt, self.base_prompt_source = resolve_base_prompt(self.cwd)
+        self.top_skills = load_top_level_skills(
+            self.cwd, self.settings, list(self._extra_skill_paths),
+            enabled=self.settings.skillsEnabled)
+        await self._emit_resources_discover(reason="reload")
+        session = self._active_session
+        if session is not None:
+            self._started_sessions.discard(session.id)
+            await self.start_session(session, reason="reload")
+        else:
+            self.notes.append("ctx.reload():扩展模块不会重新 import(要重启进程);"
+                              "技能与提示词已重扫")
+
+    async def emit_session_shutdown(self, reason: str,
+                                    target_session_file: str | None = None) -> None:
+        """发 `session_shutdown`(退出 / 重载 / 换会话之前)。
+
+        幂等由调用方保证(同一会话只发一次) —— 这里只负责派发与错误隔离。
+        """
+        if not self.bus.has("session_shutdown"):
+            return
+        payload: dict = {"reason": reason}
+        if target_session_file:
+            payload["targetSessionFile"] = target_session_file
+        result = await self.bus.emit("session_shutdown", payload,
+                                     ctx=self.extension_ctx())
+        for src, exc in result.errors:
+            self.notes.append(f"扩展 {src} 的 session_shutdown 处理失败: {exc}")
+
+    async def _emit_resources_discover(self, reason: str = "startup") -> None:
+        """发 `resources_discover`:扩展可以再补技能/提示词/主题路径。
+
+        pi 的形状是返回 `{skillPaths, promptPaths, themePaths}` 三个绝对路径列表。
+        qi 收到后**真加载**:技能进 `top_skills`,提示词/主题路径进 `self.extra_resource_paths`
+        (前端/TUI 从那里取),所以「扩展提供资源」不是只收返回值。
+        """
+        if not self.bus.has("resources_discover"):
+            return
+        result = await self.bus.emit(
+            "resources_discover", {"cwd": str(self.cwd), "reason": reason},
+            ctx=self.extension_ctx())
+        for src, exc in result.errors:
+            self.notes.append(f"扩展 {src} 的 resources_discover 处理失败: {exc}")
+        for key in ("skillPaths", "skill_paths"):
+            for raw in result.payload.get(key) or ():
+                path = Path(str(raw)).expanduser()
+                if not path.exists():
+                    self.notes.append(f"resources_discover 给的技能路径不存在: {path}")
+                    continue
+                # 给的是「技能根」还是「某个技能目录」?两种都认 —— pi 传根,而扩展作者
+                # 很容易直接指向自己的 `skills/mine/`。
+                root = path.parent if (path / "SKILL.md").is_file() else path
+                try:
+                    found = load_top_level_skills(self.cwd, self.settings, [root],
+                                                  enabled=self.settings.skillsEnabled)
+                except Exception as exc:  # noqa: BLE001 坏技能目录不该弄崩启动
+                    self.notes.append(f"resources_discover 的技能路径加载失败({path}): {exc}")
+                    continue
+                self.top_skills = [*self.top_skills, *found]
+        for key in ("promptPaths", "prompt_paths", "themePaths", "theme_paths"):
+            for raw in result.payload.get(key) or ():
+                path = Path(str(raw)).expanduser()
+                if path.exists():
+                    self.extra_resource_paths.append(path)
+                else:
+                    self.notes.append(f"resources_discover 给的路径不存在: {path}")
+
+    async def before_session_op(self, event: str, payload: dict) -> dict | None:
+        """`session_before_switch` / `_fork` / `_tree` 的**公开**入口。
+
+        前端在**用户发起**的会话操作(`/new` `/resume` `/fork` `/tree`)前调它。
+        让用户按键与扩展调 `ctx.fork()` 走**同一道闸门** —— 否则“扩展能拦扩展发起的
+        操作,却拦不住用户按的键”,闸门就名不副实。返回 `{cancel: true}` 即拦下。
+        """
+        return await self._session_gate(event, payload, self.extension_ctx())
+
+    def notify_session_tree(self, new_leaf_id: str | None) -> None:
+        """前端完成一次树跳转后通知扩展(`session_tree`)。"""
+        self._emit_notice("session_tree", {"newLeafId": new_leaf_id})
+
+    def _emit_notice(self, event: str, payload: dict) -> None:
+        """发一个**通知型**扩展事件(同步入口,不阻塞调用方)。
+
+        `bus.emit` 是 async,而 `set_model` 这类调用点在 UI 的同步路径上 —— 用一个
+        后台任务跑完全够(通知型事件的返回值本来就被忽略),避免把 UI 路径改成 async。
+        没订阅时**不建任务**(零扩展零开销)。
+        """
+        if not self.bus.has(event):
+            return
+        payload = dict(payload)
+        payload["session"] = self._active_session.id if self._active_session else None
+
+        async def _run() -> None:
+            result = await self.bus.emit(event, payload,
+                                         ctx=self.extension_ctx(session=self._active_session))
+            for src, exc in result.errors:
+                self.notes.append(f"扩展 {src} 的 {event} 处理失败: {exc}")
+
+        try:
+            asyncio.get_running_loop().create_task(_run())
+        except RuntimeError:
+            # 没在事件循环里(如脚本直接构造 runtime):通知型事件丢掉不影响主流程
+            return
+
+    # ── 主流程 ──
+    def _history(self, session: Session) -> list:
+        """当前分支的上下文 = 最近一次压缩摘要 + 压缩点之后的消息(+ 分支摘要)。
+
+        pi 的语义:压缩后模型看到的是 `system | summary | firstKeptEntryId 起头的消息`。
+        没压过时退回旧的「最近 40 条」简易窗口 —— 那时压缩还没接管窗口。
+        """
+        branch = session.branch()
+        last_compaction = next((e for e in reversed(branch)
+                                if e.get("type") == "compaction"), None)
+        out: list[ChatMessage] = []
+        keep_from = 0
+        if last_compaction is not None:
+            out.append(summary_context_message(str(last_compaction.get("summary") or "")))
+            first_kept = str(last_compaction.get("firstKeptEntryId") or "")
+            keep_from = next((i for i, x in enumerate(branch)
+                              if str(x.get("id")) == first_kept), len(branch))
+        for e in branch[keep_from:]:
+            kind = e.get("type")
+            if kind == "branch_summary":
+                out.append(summary_context_message(str(e.get("summary") or ""), kind="branch"))
+            elif kind == "message" and e.get("role") != "system":
+                d = dict(e)
+                d.pop("type", None); d.pop("ts", None); d.pop("agent_id", None)
+                out.append(chat_message_from_dict(d))
+        return out if last_compaction is not None else out[-40:]
+
+    # ── 上下文压缩(pi 的 /compact + 自动压缩)──
+    def _compaction_options(self) -> tuple[bool, int, int]:
+        """读取 `settings.compaction`:`(enabled, reserveTokens, keepRecentTokens)`。"""
+        raw = self.settings.compaction or {}
+        enabled = bool(raw.get("enabled", True))
+        reserve = raw.get("reserveTokens")
+        keep = raw.get("keepRecentTokens")
+        return (enabled,
+                reserve if isinstance(reserve, int) and reserve > 0 else DEFAULT_RESERVE_TOKENS,
+                keep if isinstance(keep, int) and keep > 0 else DEFAULT_KEEP_RECENT_TOKENS)
+
+    def _context_window(self) -> int:
+        spec = getattr(self.llm_exec, "spec", None)
+        window = getattr(spec, "context_window", 0)
+        return window if isinstance(window, int) else 0
+
+    async def _maybe_auto_compact(self, session: Session):
+        """开新一回合前检查上下文体积:超了就先自动压一次(pi 的 auto-compaction)。
+
+        预算口径:分支上会进上下文的内容 + 基座提示词;阈值 = `contextWindow - reserveTokens`。
+        压缩失败不应该把整轮卡死 —— 只报错,继续跑。
+        """
+        enabled, reserve, _keep = self._compaction_options()
+        window = self._context_window()
+        if not enabled or window <= 0:
+            return
+        # 用**重建后的上下文**估算,不是原始 entry 之和 —— 压缩过的内容不该再计入
+        base = self.base_prompt or default_base_prompt()   # 无自定义基座时按代码内默认计入
+        tokens = messages_tokens(self._history(session)) + estimate_tokens(base)
+        if not should_compact(tokens, window, enabled=enabled, reserve_tokens=reserve):
+            return
+        yield AgentEvent(kind="compaction_start", text="正在自动压缩上下文…",
+                         data={"auto": True, "tokens": tokens, "contextWindow": window})
+        try:
+            entry = await self.compact_session(session)
+        except Exception as exc:  # noqa: BLE001 压缩失败不能拖垮这一轮
+            yield AgentEvent(kind="error", text=f"自动压缩失败(继续本轮): {exc}")
+            return
+        if entry is not None:
+            yield AgentEvent(kind="compaction_end", text=str(entry.get("summary") or ""),
+                             data={"auto": True, "tokensBefore": entry.get("tokensBefore"),
+                                   "entry": entry})
+
+    async def compact_session(self, session: Session,
+                              instructions: str | None = None) -> dict | None:
+        """执行一次压缩并落盘;没什么可压时返回 None(调用方据此提示用户)。
+
+        **这是压缩的唯一入口**(TUI 的 `/compact` 与自动压缩都走它),所以 P-E3d-2 的三个
+        事件都在这一处发:
+
+        - `session_before_compact`:可 `{cancel: true}` 拦下这次压缩,也可以 `{summary: "…"}`
+          自带摘要 —— 自带时**不调模型**(扩展可能比模型更清楚该记住什么);
+        - `session_compact`:成功落盘后(带 `entry`);
+        - `session_compact_failed`:失败时**先发事件再把异常抛出去** —— 失败必须传到调用方,
+          但扩展也该看得见。
+
+        payload 键名用 snake_case(与其它事件一致);`cancel` / `summary` 是文档里那两个契约键。
+        """
+        _enabled, _reserve, keep = self._compaction_options()
+        prep = prepare_compaction(session.branch(), keep_recent_tokens=keep)
+        if prep is None:
+            return None
+        if self.bus.has("session_before_compact"):
+            result = await self.bus.emit_until(
+                "session_before_compact",
+                {"instructions": instructions, "tokens_before": prep.tokens_before},
+                ctx=self.extension_ctx(), stop_keys=("cancel",))
+            for source, exc in result.errors:
+                self.notes.append(f"扩展 {source} 的 session_before_compact 处理失败: {exc}")
+            if result.payload.get("cancel"):
+                return None
+            provided = result.payload.get("summary")
+            if isinstance(provided, str) and provided.strip():
+                # 与 `compaction.compact()` 造同一个形状(只是摘要来自扩展、usage 为空)
+                entry = {"type": "compaction", "summary": provided.strip(),
+                         "firstKeptEntryId": prep.first_kept_entry_id,
+                         "tokensBefore": prep.tokens_before, "usage": {}}
+                self.sessions.append(session, entry)
+                self._emit_notice("session_compact",
+                                  {"entry": entry, "summary": entry["summary"],
+                                   "provided": True})
+                return entry
+        try:
+            entry = await compact(self.llm_exec, prep, instructions=instructions)
+        except Exception as exc:      # noqa: BLE001 先让扩展看见,再原样抛给调用方
+            self._emit_notice("session_compact_failed", {"error": str(exc)})
+            raise
+        self.sessions.append(session, entry)
+        self._emit_notice("session_compact",
+                          {"entry": entry, "summary": str(entry.get("summary") or ""),
+                           "provided": False})
+        return entry
+
+    async def summarize_branch_for_jump(self, session: Session, source_branch: list[dict],
+                                        from_id: str | None, target_id: str | None
+                                        ) -> dict | None:
+        """`/tree` 跳到别的分支时,把「被放弃的那段」压成摘要挂到新位置。
+
+        `source_branch` 必须由调用方在**移动 position 之前**取好:`/tree` 一移动 current,
+        再调 `session.branch()` 拿到的就是目标分支了(摘要会静默变成空)。
+        """
+        # 先过 `branchSummary.skipPrompt` 与"要不要摘要"这一问(pi 的 `/tree` 行为):
+        # `skipPrompt: true` = **不问也不摘要**;否则问一句,默认"不摘要" —— 无前端时
+        # `ui.confirm` 返回调用方给的 default,正好就是 pi 的 "defaults to no summary"。
+        if branch_summary_skip_prompt(self.settings):
+            return None
+        if not await self.ui.confirm("要把被放弃的那段压成摘要吗?", default=False):
+            return None
+        target_branch = session.branch(target_id)
+        entries = branch_to_summarize(source_branch, from_id, target_branch)
+        if not entries:
+            return None
+        summary, usage = await summarize_branch(self.llm_exec, entries)
+        if not summary:
+            return None
+        entry = {"type": "branch_summary", "summary": summary,
+                 "fromId": from_id, "usage": usage}
+        # 挂到跳过去的位置下(所以新 leaf 就是这条摘要)
+        self.sessions.set_position(session, target_id)
+        self.sessions.append(session, entry)
+        return entry
+
+    async def _emit_input(self, text: str, session: Session, source: str,
+                          abort: AbortSignal | None) -> tuple[str, dict | None, str | None]:
+        """派发 `input`(pi 的 input 事件):可拦截 / 改写 / 吞掉。
+
+        返回 `(最终文本, handled 裁决, 裁决者)`;裁决非空表示扩展接管了这一轮。
+
+        **两个键,两种含义**(不能合):
+        * `text` —— **改写后的用户输入**(`transform` 用);
+        * `reply` —— **扩展给用户的答复**(`handled` 用)。
+
+        分开不是洁癖:裁决的字段会被 patch 进 payload,如果两者同名,扩展的答复就会被
+        当成用户输入落盘 —— 测试里真的出现过用户消息变成 "pong" 的那种结果。
+        pi 不需要区分是因为它的 `handled` 不带文本(靠 `ctx.ui` 自己展示);
+        qi 的 `ctx.ui` 要到 P-E3 才有,所以这里要一个 `reply`。
+        """
+        if not self.bus.has("input"):
+            return text, None, None
+        result = await self.bus.emit_until(
+            "input",
+            {"text": text, "source": source, "session": session.id},
+            ctx=self.extension_ctx(abort),
+            stop_values={"action": ("handled",)})
+        for src, exc in result.errors:
+            self.notes.append(f"扩展 {src} 的 input 处理失败: {exc}")
+        final = result.payload.get("text")
+        return (str(final) if final is not None else text), result.result, result.stopped_by
+
+    async def _handled_turn(self, session: Session, verdict: dict, source: str | None):
+        """扩展接管了这一轮(pi 的 `action: handled`):**不跑 agent**。
+
+        仍然**落盘助手侧**—— 否则回放里这一轮凭空消失,而“直播看得见、刷新就没了”
+        是本仓反复出现过的那类不一致。用户消息由 `stream()` 先落过了(那是“用户确实
+        说了这句话”的记录,与“谁处理了它”无关)。
+
+        没给 `reply` 时给一句占位:`ctx.ui` 要到 P-E3 才有,现在扩展没有别的展示
+        通道,静默吞掉会让用户以为程序卡了。
+        """
+        agent = "extension"
+        reply = str(verdict.get("reply") or "").strip()
+        self._persist_final(session, agent, reply or INPUT_HANDLED_PLACEHOLDER)
+        yield AgentEvent(kind="text", agent=agent, text=reply or INPUT_HANDLED_PLACEHOLDER)
+        yield AgentEvent(kind="agent_end", agent=agent, text=reply,
+                         data={"messages": [], "handled_by": source,
+                               "usage": {"turns": 0, "context_tokens": 0}})
+
+    async def _before_agent_start(self, text: str, tools: list[str],
+                                  abort: AbortSignal | None) -> tuple[str, str | None]:
+        """造出本轮的 system prompt,并坐许扩展改它(`before_agent_start`,链式)。
+
+        返回 `(system_prompt, 注入的消息)`。
+
+        **角色层不在 core 里**:qi-agents 通过这个钩子把角色说明拼进来(它返回的
+        `system_prompt` 会链式生效)。core 只拼「基座 + 项目上下文 + 技能 + cwd」。
+
+        注入的消息(pi 的 `{message: …}`)收字符串或 `{"content": …}`。按 pi 的语义它是
+        **持久**的(落盘,下一轮仍在上下文里),所以落盘由调用方(`_stream_inner`)做。
+        """
+        built = build_system_prompt(self.base_prompt,
+                                    cwd=self.workdir,
+                                    tools=self.catalog.resolve(tools),
+                                    skills=self.top_skills,
+                                    append=self.append_system_prompt,
+                                    # `--no-context-files` → 显式空列表(不是 None:None 会去读)
+                                    context_files=[] if self._no_context_files else None)
+        if not self.bus.has("before_agent_start"):
+            return built, None
+        result = await self.bus.emit(
+            "before_agent_start",
+            {"prompt": text, "system_prompt": built, "agent": CORE_AGENT_NAME},
+            ctx=self.extension_ctx(abort))
+        for src, exc in result.errors:
+            self.notes.append(f"扩展 {src} 的 before_agent_start 处理失败: {exc}")
+        changed = result.payload.get("system_prompt")
+        raw = result.payload.get("message")
+        injected: str | None = None
+        if isinstance(raw, str):
+            injected = raw.strip() or None
+        elif isinstance(raw, dict):
+            injected = str(raw.get("content") or "").strip() or None
+        final = str(changed) if changed else built
+        # 让 `ctx.getSystemPrompt()` 看到的是**模型真正收到的那一份**(含扩展改写)
+        self._last_system_prompt = final
+        return final, injected
+
+    async def stream(self, text: str, session: Session, agent_override: str | None = None,
+                     abort: AbortSignal | None = None, source: str = "interactive"):
+        """处理一轮用户输入,产出事件。
+
+        **`agent_override` 已不再有任何作用(P-E4c 遗留)**:它此前是"这一轮直派哪个
+        agent"的入口,而 core 收窄成单 agent 之后角色归 qi-agents(靠 `before_agent_start`
+        改提示词,E14)—— 流水线里没有任何地方读它了。参数留着不删是为了让旧调用点
+        (qi-web 曾用它)不因签名变化而崩,但**它不会生效、也不报错**,所以:
+        要"以某个角色跑"请用 qi-agents 的 `--ext agent=<名>`,或自己挂 `before_agent_start`。
+        (web 端正是栽在这里 —— 界面显示着角色、提示词里却没有;见 docs/extensions.md §6.1。)
+
+        `source` 进 `input` 事件的 payload(交互式 / 无头 / rpc)—— 扩展据此决定
+        “要不要弹问”。目前调用方都用默认值:精确标签等真正需要它的人来传。
+
+        `abort` 透传给 runner(协作式中断,见 abort.py)。即使被**硬取消**
+        (`CancelledError`:web 的客户端 abort、TUI 的强制终止),本方法也会先把已有文本
+        落盘再往上抛 —— 否则用户看过的半截回答在会话文件里消失(直播与回放不一致)。
+        """
+        # 回合内把会话绑在 runtime 上:扩展的 `appendEntry` / `ctx.session_manager` 靠它。
+        # 用 wrapper + `finally` 而不是在主体里包 `try`:主体有十几个 `return`
+        # (handled 提前结束、无 agent、错误返回…),逐个清一定会漏 —— 而漏掉的后果是
+        # “回合外的写落到上一个会话里”,那是很难查的一类串状态。
+        self._active_session = session
+        # `ctx.isIdle()` / `ctx.waitForIdle()` / `ctx.abort()` 靠这三个字段。
+        # 与 `_active_session` 同一个 wrapper:`finally` 里恢复,否则硬取消会把它们永远
+        # 留在“忙”的状态(下一次 `waitForIdle` 就死等)。
+        self._idle = False
+        self._idle_event.clear()
+        self._abort_signal = abort
+        try:
+            async for event in self._stream_inner(text, session, agent_override, abort, source):
+                yield event
+        finally:
+            self._abort_signal = None
+            self._active_session = None
+            self._idle = True
+            self._idle_event.set()
+
+    async def _stream_inner(self, text: str, session: Session,
+                            agent_override: str | None, abort: AbortSignal | None,
+                            source: str):
+        # 旧会话首次被使用时回填 cwd(只写一次);新会话在 create(cwd=…) 时已带
+        self.sessions.ensure_cwd(session, self.cwd)
+        # `next_turn` 档在这里送达:它说的就是“下一次用户输入时再说”,而这就是那个时刻。
+        # 排空 + 落盘之后,下面的 `_history()` 会自然把它算进上下文。
+        self._drain_messages("next_turn")
+        # `input` 在**自动压缩之前**:它处理的是“用户说了什么”,与上下文体积无关;而且
+        # 改写后的文本要影响下游全部(标题、分派、历史)。
+        text, handled, handled_by = await self._emit_input(text, session, source, abort)
+        if handled is not None:
+            self.sessions.append(session, {"type": "message", "role": "user",
+                                           "content": text, "agent_id": "extension"})
+            async for event in self._handled_turn(session, handled, handled_by):
+                yield event
+            return
+        # 自动命名:**并行**跑(不拖首字延迟),回合末尾才套用(见 `_apply_title`)。
+        # 触发条件是"这个会话还没有标题" —— 新建的与本功能上线前建的老会话都算
+        # (`has_title`:历史默认名 `tui` 也算没有,否则那两千多条老会话永远不被命名)。
+        title_task: asyncio.Task[str | None] | None = None
+        if not has_title(session.title):
+            # 输入取会话原本的第一句话,不是这一轮说的话:老会话续聊时,
+            # "接着再补个测试"会把一个讲仓库结构的会话命名成"补充测试"。
+            # (本轮的用户消息此刻还没落盘 —— 它在下面 append,所以新会话会回落到 text。)
+            title_task = asyncio.create_task(
+                suggest_title(self.llm_exec, self.first_user_text(session) or text))
+        async for event in self._maybe_auto_compact(session):
+            yield event
+        # 单 agent:core 不认识“角色”,所以这里没有分派 —— 就一个固定的运行单元。
+        # 角色(qi-agents)通过 `before_agent_start` 改提示词参与(§1.1),
+        # 而不是让 core 去选一个 agent。下面直接选上下文、落 user 消息。
+        # 顺序要紧:先取上下文(不含本轮),再把 user 消息立即落盘。
+        # 旧实现把 user 写在回合**结束后**,于是运行中刷新/断线就看不到自己说了什么;
+        # 而若先落盘再取 history,本轮输入会进上下文两次(两条同样的 user)。
+        history = self._history(session)
+        self.sessions.append(session, {"type": "message", "role": "user",
+                                       "content": text, "agent_id": CORE_AGENT_NAME})
+        # `before_agent_start` 在 user 落盘**之后**才 fire(pi 同款):扩展从
+        # `ctx.session_manager` 里就看得到本轮那句话,而且注入的 message 天然排在它后面。
+        tools = self.tool_names()
+        system_prompt, injected = await self._before_agent_start(text, tools, abort)
+        if injected:            # 注入的消息**落盘**(下一轮仍在上下文里,pi 说的 persistent message),
+            # 同时交给 runner 插到本轮 user 之后 —— 取 history 时它还不存在,所以不会重复。
+            self.sessions.append(session, {"type": "message", "role": "user",
+                                           "content": injected, "agent_id": CORE_AGENT_NAME,
+                                           "injected_by": "before_agent_start"})
+        runner = AgentRunner(
+            # 运行单元:core 只认识“提示词 + 工具名单 + 名字”(见 `RunSpec`)
+            RunSpec(name=CORE_AGENT_NAME, prompt=system_prompt, tools=tools),
+            self.catalog, self.llm_exec,
+            RunnerSettings(stop_after=self.stop_after),
+            tool_ctx=self._tool_ctx(CORE_AGENT_NAME),
+            injected_messages=[injected] if injected else None,
+            drain_injections=self._drain_messages,
+            bus=self.bus,
+            extension_ctx=lambda signal: self.extension_ctx(signal, session),
+            report=self.notes.append)
+        final_text = ""
+        partial = ""
+        # 正常结束才有(RUN_FINISHED 的 usage);硬取消那条路径拿不到。
+        end_usage: dict = {}
+        #: 并发执行时会有多条工具同时在途 —— 靠 `tool_call_id` 配对(以前是单个槽位)
+        pending_tools: dict[str, dict] = {}
+        try:
+            async for event in runner.run(text, history, abort=abort):
+                if event.kind == "agent_end":
+                    final_text = event.text
+                    end_usage = (event.data or {}).get("usage") or {}
+                elif event.kind == "text_delta":
+                    # 当前轮的增量:硬取消发生在 assistant_message 之前时,就靠它抢救半截回答
+                    partial += event.text or ""
+                elif event.kind == "assistant_message":
+                    partial = event.text or ""        # 该轮的权威全文
+                    # 思考**先**落:它发生在这条消息之前。顺序反了,回放就成了
+                    # "先回答、再思考"。
+                    self._persist_thinking(session, CORE_AGENT_NAME,
+                                           str((event.data or {}).get("thinking") or ""))
+                    if event.text and event.data.get("tool_calls"):
+                        # 宣布了工具调用的助手消息是"过程"而非最终回答 → 立刻落成 custom entry。
+                        # **立即**落盘而不缓冲到下一轮:否则它将被写在它触发的工具卡片**之后**,
+                        # 回放顺序就变成"工具卡 → 叙述",与真实因果相反。
+                        # 不带工具调用那条由回合末尾的 message entry 代表,所以不会重复。
+                        self._persist_narration(session, CORE_AGENT_NAME, event.text)
+                elif event.kind == "tool_start":
+                    call_id = str((event.data or {}).get("tool_call_id") or "")
+                    pending_tools[call_id] = {
+                        "tool": event.tool,
+                        "args": (event.data or {}).get("args") or {}}
+                elif event.kind == "tool_end":
+                    call_id = str((event.data or {}).get("tool_call_id") or "")
+                    pending = pending_tools.pop(call_id, None)
+                    if pending is None and len(pending_tools) == 1:
+                        # 兼容不给 id 的来源(第三方 AgentEvent 生产者):只有一条在途时可确定
+                        _, pending = pending_tools.popitem()
+                    if pending is None:
+                        pending = {"tool": event.tool, "args": {}}
+                    self._persist_tool(session, CORE_AGENT_NAME, event, pending)
+                yield event
+        except asyncio.CancelledError:
+            # 硬取消:收尾不做任何 await(已在取消状态),只做同步落盘
+            self._persist_final(session, CORE_AGENT_NAME, _salvaged(final_text, partial))
+            if title_task is not None:
+                title_task.cancel()      # 别把它漏在后台(它还会往会话里写)
+            raise
+
+        # 助手侧在回合结束后落盘(与旧版一致;tool 往返已在上方单独落盘)
+        self._persist_final(session, CORE_AGENT_NAME, final_text, usage=end_usage)
+        if title_task is not None:
+            await self._apply_title(session, title_task)
+        # `agent_settled`(pi):回合**真的**结束了 —— 没有重试、没有压缩残留、没有排队消息。
+        # qi 的 provider 级重试在客户端内部(那时本方法还没跑完),所以到这里就是终点;唯一要
+        # 排掉的是“还有排队消息会让它再跑一轮”的情形。
+        if self.bus.has("agent_settled") and not self.has_pending_messages():
+            settled = await self.bus.emit("agent_settled", {},
+                                         ctx=self.extension_ctx(session=session))
+            for src, exc in settled.errors:
+                self.notes.append(f"扩展 {src} 的 agent_settled 处理失败: {exc}")
+
+    def _persist_final(self, session: Session, agent: str, text: str,
+                       usage: dict | None = None) -> None:
+        """回合末尾的助手消息(正常结束与中断收尾共用)。
+
+        `usage` 落盘在本条 entry 上:它原来是**只活在流里**的(RUN_FINISHED 的
+        metadata),刷新/重开就没了 —— 于是"这个会话用了多少 token"在设置页与
+        输入卡下方都无从得知。放在助手消息上是因为它天然按轮分片(一輪一条),
+        汇总就是会话级(见 `usage_summary`)。
+
+        参数与分支摘要条目里的 `usage` 同名同义(那边是压缩那一次的用量)。
+        """
+        entry: dict = {"type": "message", "role": "assistant",
+                       "content": text or "(无文本输出)",
+                       "agent_id": agent}
+        if usage:
+            entry["usage"] = usage
+        self.sessions.append(session, entry)
+
+    @staticmethod
+    def first_user_text(session: Session) -> str:
+        """当前分支上第一条用户消息(没有就空串)。命名拿它当输入。"""
+        for entry in session.branch():
+            if entry.get("type") == "message" and entry.get("role") == "user":
+                return str(entry.get("content") or "")
+        return ""
+
+    async def _apply_title(self, session: Session, task: asyncio.Task[str | None]) -> None:
+        """把并行起的命名结果套到会话上。
+
+        **最多等 `TITLE_WAIT_S`**:命名是体验改进,但不该拖住"这一轮结束"(前端在
+        RUN_FINISHED 之后才刷新列表 —— 等太久就是可见的卡顿)。等不到就把落盘挂到
+        回调上,它完成时自己写盘:下一次刷新(下一轮 / 重开会话)就能看到标题。
+        """
+        done, _pending = await asyncio.wait({task}, timeout=TITLE_WAIT_S)
+        if task in done:
+            self._write_title(session, task.result())
+            return
+        task.add_done_callback(
+            lambda t: self._write_title(session, None if t.cancelled() else t.result()))
+
+    def _write_title(self, session: Session, title: str | None) -> None:
+        """落盘**模型给的**标题。空标题、或用户已经手动改过 → 不动。
+
+        两条都必须有:模型回垃圾时保持「未命名」好过写个垃圾进文件;而用户在流式期间
+        手动改了名,自动命名不能把它覆盖回去。
+
+        实际落盘走 `set_session_title` —— 那里同时发 `session_info_changed`,
+        所以自动命名与用户改名两条路都不会漏事件(也不会重发)。
+        """
+        if not title or has_title(session.title):
+            return
+        self.set_session_title(session, title, source="auto")
+
+    def _persist_thinking(self, session: Session, agent: str, text: str) -> None:
+        """落盘一步思考(entry `type=custom`, `custom_type=assistant_thinking`)。
+
+        与叙述同一个理由:思考是**过程**,直播时看得见(pi 的 thinking block),
+        不落盘则刷新/回放里整段消失 —— 界面上"思考与回答之间那条分隔线"也就
+        少了上半截(只剩一条孤零零的线)。
+
+        做成 `custom` 而不是 `message` 是**刻意的**:`_history()` 只读 `message`,
+        所以思考**不进 LLM 上下文**(零提示词回归风险)。
+
+        思考可能很长:与工具结果同档封顶,不让会话文件无界增长。
+        每步一条 `assistant_message`,空文本跳过。
+        """
+        if not text.strip():
+            return
+        body = (text if len(text) <= MAX_TOOL_ENTRY_CHARS
+                else text[:MAX_TOOL_ENTRY_CHARS] + "…(落盘已截断)")
+        self.sessions.append(session, {"type": "custom",
+                                       "custom_type": "assistant_thinking",
+                                       "agent": agent, "content": body})
+
+    def _persist_narration(self, session: Session, agent: str, text: str) -> None:
+        """落盘"工具调用之前"的助手叙述(custom entry,**不进对话上下文**)。
+
+        直播时这些文字由 `text_delta` 送到前端;不落盘则刷新/回放就只剩工具卡片,
+        直播与回放不一致。做成 `custom` 而非 `message` 是**刻意的**:`_history()` 只读
+        `message`,所以模型跨轮上下文完全不变(零提示词回归风险)。
+        """
+        self.sessions.append(session, {"type": "custom",
+                                       "custom_type": "assistant_narration",
+                                       "agent": agent, "content": text})
+
+    def _persist_tool(self, session: Session, agent: str, event: AgentEvent,
+                      pending: dict | None) -> None:
+        """把一次工具往返落盘(entry `type=tool`)。
+
+        补齐 `session.py` 已声明的第五类 entry(PLAN A5):此前 tool 往返**从不落盘**,
+        于是历史回放里工具卡片无法重现。`status`/`duration_ms`/`exit_code` 来自
+        AgentRunner 的结构化结果,前端不必解析 `result` 字符串。
+        """
+        data = event.data or {}
+        result = event.text or ""
+        if len(result) > MAX_TOOL_ENTRY_CHARS:
+            result = result[:MAX_TOOL_ENTRY_CHARS] + "…(落盘已截断)"
+        # 插件能给的结构可能很大(一份查询结果、一棵文件树)。同样封顶,
+        # 但**换成可渲染的标记**而不是切字符串 —— 切 JSON 会得到非法 JSON。
+        details = data.get("details")
+        if details is not None:
+            encoded = json.dumps(details, ensure_ascii=False)
+            if len(encoded) > MAX_TOOL_DETAILS_CHARS:
+                details = {"_truncated": True, "_full_chars": len(encoded)}
+        self.sessions.append(session, {
+            "type": "tool", "agent": agent, "tool": event.tool,
+            "args": (pending or {}).get("args", {}),
+            "status": data.get("status"), "duration_ms": data.get("duration_ms"),
+            "exit_code": data.get("exit_code"), "error": data.get("error"),
+            "details": details,
+            "result": result,
+        })