feat(web): replace the @ mention with an /agent command, and stage both switches until send (#122)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

packages/docs/content/server-api.en.md

@@ -249,7 +249,7 @@ interface ApprovalDecisionRequest {
 }
 ```
 
-The Web's `/model` switch has no dedicated endpoint: like the @ handoff, it composes the ordinary APIs above — session creation opens a new Session for the same Agent (the chosen model, the source Workspace carried over), then POST /tasks sends a first message opening with a `[model_switch_from]` source block (the source session id, its `tracePath`, the Workspace, and the previous model pair); the model reads that Trace file itself when it needs the earlier history.
+The Web's `/model` switch has no dedicated endpoint: like the `/agent` handoff, it composes the ordinary APIs above — session creation opens a new Session for the same Agent (the chosen model, the source Workspace carried over), then POST /tasks sends a first message opening with a `[model_switch_from]` source block (the source session id, its `tracePath`, the Workspace, and the previous model pair); the model reads that Trace file itself when it needs the earlier history.
 
 ## Streaming (SSE)
 

packages/docs/content/server-api.zh.md

@@ -247,7 +247,7 @@ interface ApprovalDecisionRequest {
 }
 ```
 
-Web 的 `/model` 模型切换没有专用接口：它按 @ handoff 的方式复用上面的普通接口——先用会话创建接口在同一 Agent 下新建 Session（选定新模型并沿用源 Workspace），再 POST /tasks 发送以 `[model_switch_from]` 源块开头的首条消息（源会话 id、其 `tracePath`、Workspace 与原模型二元组），模型需要早前历史时自行读取该 Trace 文件。
+Web 的 `/model` 模型切换没有专用接口：它按 `/agent` 交接的方式复用上面的普通接口——先用会话创建接口在同一 Agent 下新建 Session（选定新模型并沿用源 Workspace），再 POST /tasks 发送以 `[model_switch_from]` 源块开头的首条消息（源会话 id、其 `tracePath`、Workspace 与原模型二元组），模型需要早前历史时自行读取该 Trace 文件。
 
 ## 流式接口（SSE）
 

packages/docs/content/sessions-and-traces.en.md

@@ -81,7 +81,7 @@ Special case: if the latest Trace file ends with a completed compaction, that co
 
 ## Model switch (/model)
 
-The Web's `/model` command changes models the way the @ handoff does: it creates a new Session under the same Agent via the ordinary session-creation API (the chosen model, **the source session's Workspace** — so files stay reachable), and the first message opens with a `[model_switch_from]` source block — the source session id, the absolute path of its latest Trace file, the Workspace, and the previous model pair — followed by whatever the user typed. The history is **not injected** into the new context: some models require thinking payloads and `fidelity` byte-for-byte when history is replayed, which cannot cross models — instead the model reads the source Trace file itself (JSONL, one message envelope per line) when it needs the earlier context. The source session and its Trace are untouched.
+The Web's `/model` command changes models the way the `/agent` handoff does: picking a model stages it in the composer, and sending creates a new Session under the same Agent via the ordinary session-creation API (the chosen model, **the source session's Workspace** — so files stay reachable), and the first message opens with a `[model_switch_from]` source block — the source session id, the absolute path of its latest Trace file, the Workspace, and the previous model pair — followed by whatever the user typed. The history is **not injected** into the new context: some models require thinking payloads and `fidelity` byte-for-byte when history is replayed, which cannot cross models — instead the model reads the source Trace file itself (JSONL, one message envelope per line) when it needs the earlier context. The source session and its Trace are untouched.
 
 ## Field fidelity
 

packages/docs/content/sessions-and-traces.zh.md

@@ -81,7 +81,7 @@ Trace 是恢复的唯一事实来源，没有独立的会话数据库需要与
 
 ## 模型切换（/model）
 
-Web 的 `/model` 命令按 @ handoff 的方式换模型：用普通的会话创建接口在同一 Agent 下新建一个 Session（选定新模型，**沿用源会话的 Workspace**，文件因此保持可达），首条消息以 `[model_switch_from]` 源块开头——携带源会话 id、其最新 Trace 文件的绝对路径、Workspace 与原模型二元组，用户输入的剩余文字紧随其后。历史**不注入**新上下文：部分模型回放历史时要求 thinking 与 `fidelity` 逐字一致，跨模型注入不可行——模型需要早前上下文时按路径自行读取源 Trace 文件（JSONL，每行一个消息信封）。源会话与其 Trace 不受任何影响。
+Web 的 `/model` 命令按 `/agent` 交接的方式换模型：选中模型只是在输入框暂存，发送时才用普通的会话创建接口在同一 Agent 下新建一个 Session（选定新模型，**沿用源会话的 Workspace**，文件因此保持可达），首条消息以 `[model_switch_from]` 源块开头——携带源会话 id、其最新 Trace 文件的绝对路径、Workspace 与原模型二元组，用户输入的剩余文字紧随其后。历史**不注入**新上下文：部分模型回放历史时要求 thinking 与 `fidelity` 逐字一致，跨模型注入不可行——模型需要早前上下文时按路径自行读取源 Trace 文件（JSONL，每行一个消息信封）。源会话与其 Trace 不受任何影响。
 
 ## 字段保真
 

packages/docs/content/web-app.en.md

@@ -33,7 +33,7 @@ The interface language (中文 / English / system) and theme (light / dark / sys
 
 ### Creating a Conversation
 
-A new conversation starts as a draft: pick the Agent, the Workspace (via a server-side directory browser), the approval mode, the model, and the thinking level before sending the first message. The Session is created on first send, and from then on its model and Workspace are locked. Switching the thinking level or the model in the draft makes the switched-to value the new default: the level is written back to the selected Agent's `model.thinking_level` immediately, and the picked model carries over as the next conversation's default. Inside an active session the thinking level is a per-turn parameter: the composer's picker starts out showing the Agent config's level and auto-follows it until touched (sends omit the level, so config edits keep taking effect); a pick sticks for the session and rides on every subsequent send (never written back to the Agent config); the model stays locked per session — the `/model` command switches models the way the @ handoff does: it opens a new session for the same Agent on the picked model, keeping the current Workspace, whose first message carries a `[model_switch_from]` source block (source session id, Trace file path, previous model) followed by whatever was left in the composer (an interface-language auto-line when empty). In the new session that block collapses into a "switched model" banner linking back to the source conversation, and the model reads the source Trace file itself when it needs the earlier history.
+A new conversation starts as a draft: pick the Agent, the Workspace (via a server-side directory browser), the approval mode, the model, and the thinking level before sending the first message. The Session is created on first send, and from then on its model and Workspace are locked. Switching the thinking level or the model in the draft makes the switched-to value the new default: the level is written back to the selected Agent's `model.thinking_level` immediately, and the picked model carries over as the next conversation's default. Inside an active session the thinking level is a per-turn parameter: the composer's picker starts out showing the Agent config's level and auto-follows it until touched (sends omit the level, so config edits keep taking effect); a pick sticks for the session and rides on every subsequent send (never written back to the Agent config); the model stays locked per session — the `/model` command switches models the way the `/agent` handoff does: picking a model stages it as a chip in the composer, and **sending** opens a new session for the same Agent on the picked model, keeping the current Workspace, whose first message carries a `[model_switch_from]` source block (source session id, Trace file path, previous model) followed by whatever the composer held (an interface-language auto-line when empty). In the new session that block collapses into a "switched model" banner linking back to the source conversation, and the model reads the source Trace file itself when it needs the earlier history.
 
 There are four approval modes: `allow-all`, `deny-all`, `read-only` (only read-only tools pass), and `always-ask`. See [Tools and Approvals](/tools).
 
@@ -47,9 +47,9 @@ There are four approval modes: `allow-all`, `deny-all`, `read-only` (only read-o
 ### Input and Shortcuts
 
 - Enter sends, Shift+Enter inserts a newline, and images can be pasted;
-- Typing `/` opens the slash menu: trigger context compaction (`/compact`) or toggle installed Skills — chosen Skills are sent along with the message in a `[use_skills]` block;
+- Typing `/` opens the slash menu: trigger context compaction (`/compact`), hand the conversation over to another Agent (`/agent`), switch the model (`/model`) — both switch commands appear in an active session only, since a draft has nothing to switch and picks its Agent and model up front — or toggle installed Skills — chosen Skills are sent along with the message in a `[use_skills]` block;
 - While a Task is running the input stays live and the toolbar keeps a single action button: an empty composer shows **Stop**, and typing turns it into **Send**, whose behavior follows the **mid-run send mode** from the toolbar's More-settings popover (a compact extensible settings panel, also available in draft state; the choice is remembered): **Steer** (default) delivers the text mid-run as a `[user_steering]` user message with the next turn, **Queue** holds the whole message server-side as a follow-up and auto-sends it as an ordinary new message when the run finishes (an "N queued" hint shows near the input until then; the queue survives page reloads);
-- Typing `@` mentions another Agent to hand the conversation over to it;
+- `/agent` and `/model` stage their pick instead of acting on it: the chosen Agent or model becomes a chip above the text body and nothing is sent yet, so you keep typing — Enter/Send is what hands the conversation over (a new chat for that Agent) or forks it onto the chosen model, carrying the text along; with an empty composer a default message is filled in, and the chip's × cancels. Both chips are cached with the draft, so they survive a reload or a trip to another conversation together with the text. A model fork additionally waits for the Session to be idle — it continues from the Session's Trace, which a running turn or a compaction is still writing — and a line above the composer says so while it waits;
 - When human approval is required, tool calls show inline allow/deny buttons in the message stream; the approval mode can be changed mid-Session;
 - While the engine waits out a reconnect backoff (≥2s), the retry line shows a live countdown to the next attempt with inline **Retry now** (skips the remaining wait) and **Give up** (the ordinary abort) controls;
 - When the model API rejects the Session's credentials (an authentication failure), the composer grays out and disables — recoverably: the Session pins only the model reference, and credentials come from the current Project config. The notice's primary button opens the Models page; saving a new API key there unlocks the composer by itself (open tabs unlock live via a `credentials_updated` event, and after a reload the composer stays unlocked because the credential update is newer than the recorded auth failure). A "Retry" button clears the state manually for another attempt (it re-arms if the key is still bad), a completed request always clears it, and "New Session" remains as the escape to a fresh draft. The disabled composer keeps its draft selectable, so a long message that failed to send can still be copied out.

packages/docs/content/web-app.zh.md

@@ -33,7 +33,7 @@ penguin web
 
 ### 新建会话
 
-新会话从草稿开始：先选择 Agent、Workspace（服务器端目录浏览器选取）、审批模式、模型与思考等级，再发送第一条消息。Session 在首次发送时才真正创建，此后该会话的模型与 Workspace 即被锁定。草稿里切换思考等级或模型时，切换后的值即成为新的默认：思考等级立即写回所选 Agent 的 `model.thinking_level`，所选模型则作为下一个新会话的默认延续。进行中的会话里，思考等级是逐轮参数：输入区拾取器初始显示 Agent 配置的档位并自动跟随（未选择时发送不携带档位，配置修改持续生效），选定后即固定为该会话档位、随每次发送下发（不写回 Agent 配置）；模型仍在会话内锁定，改用 `/model` 命令切换模型——与 @ handoff 同一方式：在同一 Agent 下新建一个使用所选模型、沿用当前 Workspace 的会话并跳转，其首条消息携带 `[model_switch_from]` 源块（源会话 id、Trace 文件路径、原模型），输入框剩余文字随之发出（为空时发一句界面语言的自动消息）；新会话中该源块折叠为一条“已切换模型”横幅，可点击回到原会话，模型需要早前历史时按路径自行读取源 Trace 文件。
+新会话从草稿开始：先选择 Agent、Workspace（服务器端目录浏览器选取）、审批模式、模型与思考等级，再发送第一条消息。Session 在首次发送时才真正创建，此后该会话的模型与 Workspace 即被锁定。草稿里切换思考等级或模型时，切换后的值即成为新的默认：思考等级立即写回所选 Agent 的 `model.thinking_level`，所选模型则作为下一个新会话的默认延续。进行中的会话里，思考等级是逐轮参数：输入区拾取器初始显示 Agent 配置的档位并自动跟随（未选择时发送不携带档位，配置修改持续生效），选定后即固定为该会话档位、随每次发送下发（不写回 Agent 配置）；模型仍在会话内锁定，改用 `/model` 命令切换模型——与 `/agent` 交接同一方式：选中模型只是在输入框暂存为一枚 chip，**发送时**才在同一 Agent 下新建一个使用所选模型、沿用当前 Workspace 的会话并跳转，其首条消息携带 `[model_switch_from]` 源块（源会话 id、Trace 文件路径、原模型），输入框中的文字随之发出（为空时发一句界面语言的自动消息）；新会话中该源块折叠为一条“已切换模型”横幅，可点击回到原会话，模型需要早前历史时按路径自行读取源 Trace 文件。
 
 审批模式共四种：`allow-all`（全部放行）、`deny-all`（全部拒绝）、`read-only`（仅放行只读工具）、`always-ask`（每次询问），详见[工具与审批](/tools)。
 
@@ -47,9 +47,9 @@ penguin web
 ### 输入与快捷操作
 
 - Enter 发送，Shift+Enter 换行，支持粘贴图片；
-- 输入 `/` 打开快捷菜单：触发上下文压缩（`/compact`），或勾选已安装的 Skill——所选 Skill 会以 `[use_skills]` 块随消息发送；
+- 输入 `/` 打开快捷菜单：触发上下文压缩（`/compact`）、把会话交接给其他 Agent（`/agent`）、切换模型（`/model`）——两个切换命令都只在进行中的会话里提供，草稿没有可切换的对话，Agent 与模型本就在草稿页选定——或勾选已安装的 Skill——所选 Skill 会以 `[use_skills]` 块随消息发送；
 - Task 运行期间输入框保持可用，工具条只保留一个操作按钮：输入框为空时是**停止**，一旦输入内容即变为**发送**，其行为遵循工具条「更多设置」弹出分组中的**运行中发送方式**（一个可扩展的设置面板，草稿态同样可设，选择会被记忆）：**插话**（默认）把文字以 `[user_steering]` 用户消息随下一轮送达运行中的 Agent；**排队** 把整条消息暂存在服务端，本轮结束后自动作为普通新消息发出（期间在输入框附近显示「N 条已排队」提示；队列存放在服务端，刷新页面不丢失）；
-- 输入 `@` 提及其他 Agent，将会话交接给它；
+- `/agent` 与 `/model` 都是暂存而非立即生效：选中的 Agent 或模型只在文本区上方留下一枚 chip，此时不发送任何内容，可以继续输入——按 Enter / 点发送才真正交接（为该 Agent 新开一个对话）或换用所选模型继续本对话，输入的文字随之带走；正文为空时自动填入默认消息，点 chip 上的 × 即可取消。两枚 chip 都随草稿缓存，刷新页面或切到别的会话再回来时与文字一同恢复；其中切换模型还需等待会话空闲——新会话要从本会话的 Trace 接续，而运行中的一轮或压缩仍在写入——等待期间输入框上方会给出说明；
 - 需要人工审批时，工具调用在消息流中内联显示“允许 / 拒绝”按钮；审批模式在会话中途可随时调整；
 - 引擎在重连退避等待（≥2 秒）期间，重试提示行会实时倒计时到下一次尝试，并内联提供**立即重试**（跳过剩余等待）与**放弃**（普通中断）两个按钮；
 - 模型 API 拒绝该 Session 的凭据（鉴权失败）时，输入框会置灰禁用——但可恢复：Session 锁定的只是模型引用，凭据取自当前 Project 配置。提示条的主按钮跳转到模型配置页；在那里保存新的 API key 后输入框会自动解锁（已打开的标签页经 `credentials_updated` 事件即时解锁；刷新后也保持解锁，因为凭据更新时间晚于记录的鉴权失败时间）。「重试」按钮可手动清除该状态再试一次（key 仍无效时会重新变灰），一次成功的请求总会清除该状态，「新建会话」仍作为跳到全新草稿的出口。禁用态的输入框保留草稿且可选中——发送失败的长消息仍能复制出来。