@muzi3/herdr 0.2.3 → 0.3.1

package/extensions/pane-agent-tools/index.ts

@@ -1,33 +1,37 @@
 /**
- * Herdr pane / agent 工具：`herdr_layout`、`herdr_pane`、`herdr_agent`。
+ * Herdr 管理工具面：八个动词工具，逐个操作对齐 dsh 的
+ * `@muzi3/dsh-plugin-herdr-tools` manager 面（`src/manager.js`）：
  *
- * Fork 自 `@ogulcancelik/pi-herdr` 0.4.0（MIT，Copyright (c) 2026 Can Celik）。
- * 上游许可全文见同包根目录 `LICENSE.MIT`，来源与改动说明见 README。
+ *   herdr_overview · herdr_read · herdr_wait · herdr_prompt
+ *   herdr_run · herdr_create · herdr_agent_start · herdr_close
  *
- * 相对上游的改动（3 行）：`pane run` / `pane send-text` / `pane send-keys` 在
- * herdr 0.9.0 上成功时退出码为 0 且 stdout 为空（0.9.5 复测同）。上游用 execHerdrJson 会额外要求
- * JSON envelope，于是每一次写操作都误报 "Expected JSON output from herdr ..."
- * —— 即使命令早已成功下发到目标 pane。
+ * 与 dsh 的默认面（`herdr_layout` / `herdr_pane` / `herdr_agent` 三个 action 风格
+ * 工具）不同，这里一个动词一个工具。pi 早期版本用的是 action 面，已整体替换：
+ * 两套不共存，否则同名能力会有两种调用方式，模型选哪套全凭运气。
  *
- * 这三处改用 execHerdr：它只校验退出码，并把 stderr/stdout 上的结构化 herdr 错误
- * 经 parseHerdrError 抛出，所以真实失败照旧报错，只有那个不成立的“stdout 必须非空”
- * 约束被去掉。`pane close` / `pane wait-output` / `agent send-keys` 确实返回 JSON
- * envelope，保持 execHerdrJson。回归测试见 tests/pane-agent-tools.test.ts。
+ * 复用了 dsh 侧的全部判据语义：
+ *   - 统一信封 `{ ok, exitCode, timedOut?, output, note?, via? }`。exitCode：0 成功 /
+ *     1 herdr 错误 / 2 参数或前置校验失败 / -1 本地超时。`note` 是判据提示，渲染在正文前。
+ *   - 每次 herdr 调用都有本地截止时间（默认 120s）；本地超时是「没观测到」，不是失败：
+ *     返回 timedOut 而不是把错误抛给调用方。
+ *   - herdr 的 `timeout` / `agent_prompt_stalled` 都是「没观测到」，不是失败。stalled 尤其
+ *     危险 —— prompt 已经下发，重发就是重复下发。
+ *   - `agent prompt` 只有 herdr 自己命名并激活的 agent 才收；自报状态的 agent（dsh-tui）
+ *     回 `agent_not_ready`，此时回退成 `pane run` 直接键入，`via` 说明实际走了哪条路。
+ *   - `herdr_read` 默认 digest：只回「前段命中的审批/报错行 + 尾部 30 行」，要看整段传
+ *     `mode: "raw"`。失败从不压缩 —— 错误原文本身就是证据。
+ *   - 下发类工具（prompt / run / close）拒绝以自己所在的 pane 为目标：那等于给自己喂输入，
+ *     会打断正在进行的这一轮。prompt 另外拒绝插队正在 working 的 agent（除非 force）。
  *
- * 状态检测加固：
- *   - herdr 的 error.code 会随错误一起抛出（herdrError/herdrErrorCode）。timeout 与
- *     agent_prompt_stalled 表示“没观测到”，不是失败：前者降级为 matched:false +
- *     pane 尾部输出，后者降级为 submitted:true + stalled:true，避免调用方误判为命令
- *     失败，或因为一条假错误把 prompt 重复下发一遍。
- *   - wait_output 的 match 未显式指定 regex 时，含正则元字符的 pattern 按正则处理。
- *     字面量语义下 `a|b` / `log \$` 永远不可能命中，只会白等满 timeout。
- *   - 命中行包含本进程刚下发的命令文本时标 echoedInput —— 那多半是命令回显行，而不是
- *     命令产生的输出（回显在命令还没跑完时就已经存在）。
- *   - agent_blocked 单独识别：目标卡在审批/提问弹窗时 herdr 会在发送任何输入前就拒绝，
- *     因此不能像 stalled 那样判为“已下发”，也不能靠重试绕过（详见 isPromptBlocked）。
+ * pi 侧保留的两处加固（dsh manager 面没有，见 README）：
+ *   - `agent_blocked`：目标卡在审批/提问弹窗时 herdr 在发送任何输入**之前**就拒绝，所以判为
+ *     未下发（exitCode 2）并指向「先看清阻塞界面」，而不是 `agent_prompt_stalled` 那样判为
+ *     已下发。
+ *   - `agent start --kind` 用枚举约束，必须与 `herdr agent start --help` 一致（0.9.5 共 24 个），
+ *     tests/ 里有对账用例。
  *
- * 维护：`agent start --kind` 的枚举必须与 `herdr agent start --help` 一致（0.9.5 共 24 个）。
- * herdr 每加一个 agent 就多一个 kind，枚举写死就会让新 kind 起不来 —— tests/ 里有对账用例。
+ * 环境变量（pi 侧用 PI_ 前缀，语义同 dsh 的 DSH_HERDR_*）：`PI_HERDR_PROMPT_GUARD`（默认 on，
+ * 置 off 关闭插队保护）、`PI_HERDR_READ_MODE`（默认 digest）、`PI_HERDR_READ_TAIL_LINES`（默认 30）。
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -37,10 +41,8 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 type AgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
-type ReadSource = "visible" | "recent" | "recent-unwrapped" | "detection";
-type WaitOutputSource = Exclude<ReadSource, "detection">;
 type SplitDirection = "right" | "down";
-type OutputFormat = "text" | "ansi";
+type ReadMode = "digest" | "raw";
 
 interface WorkspaceInfo {
 	workspace_id: string;
@@ -49,14 +51,6 @@ interface WorkspaceInfo {
 	agent_status: AgentStatus;
 }
 
-interface TabInfo {
-	tab_id: string;
-	workspace_id: string;
-	label: string;
-	focused: boolean;
-	agent_status: AgentStatus;
-}
-
 interface PaneInfo {
 	pane_id: string;
 	workspace_id: string;
@@ -106,26 +100,53 @@ interface HerdrJsonEnvelope {
 	};
 }
 
-interface WaitOutputResult {
-	pane_id: string;
-	matched_line: string;
-	read?: { text?: string };
+/** 八个工具共用的结果信封：渲染成正文，同时作为 `details` 交给渲染层。 */
+interface Envelope {
+	ok: boolean;
+	exitCode: number;
+	timedOut?: boolean;
+	output: string;
+	note?: string;
+	via?: string;
 }
 
+/** 一次 herdr 调用的结局：成功 / 本地截止时间到期 / 真失败。 */
+type Failure =
+	| { ok: false; timedOut: false; error: unknown }
+	| { ok: false; timedOut: true; error?: undefined };
+type Attempt<T> = { ok: true; value: T } | Failure;
+
 const StatusEnum = StringEnum(["idle", "working", "blocked", "done", "unknown"] as const, {
-	description: "Agent lifecycle state",
+	description: "要等的 agent 生命周期状态",
 });
 
 const ReadSourceEnum = StringEnum(["visible", "recent", "recent-unwrapped", "detection"] as const, {
-	description: "Terminal snapshot source",
+	description: "终端快照来源，默认 recent-unwrapped（日志与长文本首选）",
 });
 
-const OutputFormatEnum = StringEnum(["text", "ansi"] as const, {
-	description: "Output format; ansi preserves terminal styling",
+const ReadModeEnum = StringEnum(["digest", "raw"] as const, {
+	description: "默认 digest：压成「前段信号行 + 尾部」；要整段原文传 raw",
+});
+
+/**
+ * 八个工具共用的结构化结果：codemode 脚本拿它做过滤，模型仍看 content 里的渲染文本。
+ * 与 Envelope 同形，免得多出一套真值。
+ */
+const envelopeOutputSchema = Type.Object({
+	ok: Type.Boolean({ description: "这条 herdr 命令是否成功" }),
+	exitCode: Type.Number({ description: "退出码；-1 表示本地截止时间到期" }),
+	timedOut: Type.Optional(Type.Boolean({ description: "本地截止时间是否到期" })),
+	output: Type.String({ description: "正文：digest 压缩后的信号行 + 尾部，或 raw 全文" }),
+	note: Type.Optional(Type.String({ description: "判据提示，或失败时的说明" })),
+	via: Type.Optional(Type.String({ description: "实际走了 agent 还是 pane 视图" })),
+});
+
+const CreateKindEnum = StringEnum(["workspace", "tab", "pane"] as const, {
+	description: "建 workspace、建 tab，还是切一个兄弟 pane",
 });
 
 const DirectionEnum = StringEnum(["right", "down"] as const, {
-	description: "Split direction. When omitted, the tool chooses from the source pane geometry.",
+	description: "pane 切分方向，默认从几何信息判断",
 });
 
 const AgentKindEnum = StringEnum(
@@ -155,14 +176,53 @@ const AgentKindEnum = StringEnum(
 		"maki",
 		"muse",
 	] as const,
-	{ description: "Supported coding agent kind and canonical executable" },
+	{ description: "agent 种类（如 claude / codex / pi）。必须与 `herdr agent start --help` 一致" },
 );
 
+/** 每次 herdr 调用的本地截止时间：卡死的 herdr 不能把 manager 一起挂住。 */
+const DEFAULT_LOCAL_TIMEOUT = 120_000;
+
 /**
- * 字面量里带这些字符的 pattern（`a|b`、`log \$`）在字面量语义下永远不可能命中，
- * 只会白等满 timeout，所以 wait_output 在未显式指定 regex 时按正则解释它们。
+ * herdr_wait 的本地截止时间比它向 herdr 要的等待略长，让 herdr 自己的 timeout 先到；
+ * 本地那条只兜「herdr 卡死」。
  */
-const REGEX_METACHARS = /[|()[\]{}^$*+?\\]/;
+const WAIT_LOCAL_MARGIN = 30_000;
+const WAIT_DEFAULT_TIMEOUT = 60_000;
+
+/** 插队保护：lancer 正在 working 的 agent 时默认拒绝下发。 */
+const PROMPT_GUARD_ON = (process.env.PI_HERDR_PROMPT_GUARD ?? "on") !== "off";
+
+const readTailFromEnv = Number(process.env.PI_HERDR_READ_TAIL_LINES ?? 30);
+const READ_TAIL_LINES = Number.isFinite(readTailFromEnv) && readTailFromEnv > 0 ? readTailFromEnv : 30;
+const READ_MODE_DEFAULT: ReadMode = process.env.PI_HERDR_READ_MODE === "raw" ? "raw" : "digest";
+
+/**
+ * digest 从前段捞出来的信号行：审批、报错、超时。判据和 dsh 侧一致 —— manager 的
+ * 「有没有东西在等人」判断是按这批词训出来的。
+ */
+const SIGNAL_RE =
+	/(\[y\/N\]|\(y\/n\)|是否|确认|同意|approve|allow|permission|do you want|waiting for|error|exception|traceback|failed|失败|报错|超时|？|\?$)/i;
+
+/** herdr_overview 每个列表默认返回多少条，与 dsh 侧一致。 */
+const OVERVIEW_LIST_LIMIT = 50;
+
+/** agent 名字的约束（herdr CLI 自己也是这条）。 */
+const AGENT_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/;
+
+/** herdr_agent_start 的 timeout 边界，dsh 侧同样在 body 里判。 */
+const START_TIMEOUT_MIN = 3_000;
+const START_TIMEOUT_MAX = 300_000;
+
+/** exitCode 的语义，让 note 读起来和 dsh 侧一样。 */
+const EXIT_NOTE: Record<number, string> = {
+	1: "herdr 侧错误（消息来自它的结构化错误）",
+	2: "参数或前置校验失败（没有下发给 herdr）",
+};
+
+const LOCAL_TIMEOUT_NOTE = "本地等待超时，未观测到结果（不等于命令失败）；用 herdr_wait / herdr_read 复查再决定。";
+
+const SELF_PANE_REFUSAL =
+	"拒绝对自己所在的 pane 下发：那等于给自己喂输入，会打断你正在进行的这一轮。要操作别的 pane，先从 herdr_overview 拿完整 pane id。";
 
 interface HerdrErrorDetail {
 	code?: string;
@@ -182,7 +242,7 @@ function parseHerdrError(output: string): HerdrErrorDetail | null {
 	}
 }
 
-/** 构造带 herdr code 的错误，让调用方能区分“检测未达成”和真正的失败。 */
+/** 构造带 herdr code 的错误，让调用方能区分「检测未达成」和真正的失败。 */
 function herdrError(message: string, code?: string): Error {
 	const error = new Error(message) as Error & { herdrCode?: string };
 	if (code) error.herdrCode = code;
@@ -193,17 +253,22 @@ function herdrErrorCode(error: unknown): string | undefined {
 	return error instanceof Error ? (error as Error & { herdrCode?: string }).herdrCode : undefined;
 }
 
+const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
 /**
- * herdr 的 timeout / agent_prompt_stalled 表示“没观测到”，不是失败。
- * code 是主要判据，文案匹配作为兜底（个别版本可能不带结构化 code）。
- * stalled 的文案见过两种：旧版 `no observed state change ... state_change_seq remained N`，
- * 0.9.0 起 `no observed working or blocked state within 5000 ms; current status is idle`
- * （0.9.5 二进制里仍是这段措辞）。
+ * herdr 的 timeout 表示「没观测到」。code 是主判据，文案匹配作为兜底
+ * （个别版本可能不带结构化 code）。
  */
 function isHerdrTimeout(error: unknown): boolean {
 	return herdrErrorCode(error) === "timeout" || (error instanceof Error && /timed out waiting for/i.test(error.message));
 }
 
+/**
+ * `agent_prompt_stalled` 是「submission accepted」之后 5s 内没观测到 working/blocked，
+ * prompt 已经下发 —— 这是启发式，不能当成下发失败。文案见过两种：旧版
+ * `no observed state change ... state_change_seq remained N`，0.9.0 起
+ * `no observed working or blocked state within 5000 ms; current status is idle`。
+ */
 function isPromptStalled(error: unknown): boolean {
 	return (
 		herdrErrorCode(error) === "agent_prompt_stalled" ||
@@ -214,7 +279,7 @@ function isPromptStalled(error: unknown): boolean {
 /**
  * 目标正卡在审批/提问弹窗时，herdr 在**发送任何输入之前**就拒绝 prompt，返回 agent_blocked
  * （见 0.9.5 的 `herdr agent prompt --help` 与 api/agents.rs 的 validate_agent_prompt）。
- * 这和 stalled 相反：它确定没下发，且不该自动重试 —— 必须先看阻塞的界面再由人决定怎么答。
+ * 这和 stalled 相反：它确定没下发，也不该自动重试 —— 必须先看清阻塞的界面再由人决定怎么答。
  */
 function isPromptBlocked(error: unknown): boolean {
 	return herdrErrorCode(error) === "agent_blocked";
@@ -233,27 +298,15 @@ function formatOutput(output: string): string {
 	return `[Showing last ${truncation.outputLines} of ${truncation.totalLines} lines]\n${truncation.content}`;
 }
 
-function chooseSplitDirection(layout: PaneLayoutSnapshot, paneId: string): SplitDirection {
+function chooseSplitDirection(
+	layout: { panes: Array<{ pane_id: string; rect: PaneLayoutRect }> },
+	paneId: string,
+): SplitDirection {
 	const pane = layout.panes.find((candidate) => candidate.pane_id === paneId);
 	if (!pane) return "right";
 	return pane.rect.width >= 80 && pane.rect.width >= pane.rect.height * 2 ? "right" : "down";
 }
 
-function statusDot(theme: any, status: AgentStatus): string {
-	switch (status) {
-		case "blocked":
-			return theme.fg("warning", "●");
-		case "working":
-			return theme.fg("accent", "●");
-		case "done":
-			return theme.fg("success", "●");
-		case "idle":
-			return theme.fg("muted", "○");
-		default:
-			return theme.fg("dim", "·");
-	}
-}
-
 function agentDisplayName(agent: AgentInfo): string {
 	return agent.name || agent.display_agent || agent.agent || agent.pane_id;
 }
@@ -275,13 +328,6 @@ function summarizePane(pane: PaneInfo, currentPaneId?: string): string {
 	return `${pane.label || pane.pane_id}: [${pane.pane_id}]${flags ? ` (${flags})` : ""}${cwd ? ` ${cwd}` : ""}`;
 }
 
-function summarizeTab(tab: TabInfo): string {
-	const flags = [tab.focused ? "focused" : null, tab.agent_status !== "unknown" ? tab.agent_status : null]
-		.filter(Boolean)
-		.join(", ");
-	return `${tab.label}: [${tab.tab_id}]${flags ? ` (${flags})` : ""}`;
-}
-
 function summarizeWorkspace(workspace: WorkspaceInfo): string {
 	const flags = [
 		workspace.focused ? "focused" : null,
@@ -292,75 +338,149 @@ function summarizeWorkspace(workspace: WorkspaceInfo): string {
 	return `${workspace.label}: [${workspace.workspace_id}]${flags ? ` (${flags})` : ""}`;
 }
 
-function renderToolCall(tool: string, args: Record<string, any>, theme: any, context: any) {
+/**
+ * 截断一个 overview 列表。静默截断会被读成「全机就这些」—— 对 manager 恰是错的结论，
+ * 所以永远写出被隐藏的条数，让调用方自己决定抬 limit。
+ */
+function capList<T>(items: T[], limit: number, kind: string, summarize: (item: T) => string): string {
+	if (!items.length) return `No ${kind}.`;
+	const shown = items.slice(0, limit);
+	const body = shown.map(summarize).join("\n");
+	return shown.length < items.length ? `${body}\n[Showing ${shown.length} of ${items.length} ${kind} — raise with limit]` : body;
+}
+
+/**
+ * 把读屏压成「前段命中的信号行 + 原样尾部」。
+ *
+ * 为什么不是单纯截断：manager 既要判断又要引用这段文字，尾部必须原样留着（那是证据），
+ * 而更早的审批/失败行值得提上来。与 dsh 侧同一份实现，保证两边看到同一幅画面。
+ */
+function digestRead(output: string, tailLines: number): string {
+	const lines = output.split("\n");
+	let end = lines.length;
+	while (end > 0 && lines[end - 1].trim() === "") end -= 1;
+	const body = lines.slice(0, end);
+	if (body.length <= tailLines) return output;
+	const tail = body.slice(-tailLines);
+	const head = [`（读屏已压缩：原始 ${body.length} 行 → 尾部 ${tail.length} 行；要全量传 mode="raw"）`];
+	const signals: string[] = [];
+	for (let i = 0; i < body.length - tail.length; i += 1) {
+		if (SIGNAL_RE.test(body[i])) signals.push(`[${i + 1}] ${body[i]}`);
+	}
+	if (signals.length > 0) head.push("## 前段命中的信号行（审批/报错）", ...signals.slice(-20));
+	head.push("## 尾部（原样）", ...tail);
+	return head.join("\n");
+}
+
+/** 信封渲染：note 是判据提示，所以排在最前面。 */
+function renderEnvelope(value: Envelope): string {
+	const head = value.note === undefined ? "" : `${value.note}\n`;
+	const body = value.output.length > 0 ? value.output : "（无输出）";
+	return (head + body).trim();
+}
+
+function envelopeResult(value: Envelope) {
+	return {
+		content: [{ type: "text" as const, text: renderEnvelope(value) }],
+		details: value,
+		// 声明了 outputSchema 的工具：脚本收结构化值，模型仍收上面的渲染文本。
+		structuredContent: value,
+	};
+}
+
+/** 自己拒绝的决定，发生在任何 herdr 调用之前。 */
+const refusal = (note: string): Envelope => ({ ok: false, exitCode: 2, output: "", note });
+
+/** 来自 herdr 侧前置条件的拒绝。 */
+const precondition = (message: string): Envelope => ({
+	ok: false,
+	exitCode: 2,
+	output: message,
+	note: EXIT_NOTE[2],
+});
+
+/** 失败结局映射成信封。成功时不会调用它。 */
+function failureEnvelope(outcome: Failure, extra: Partial<Envelope> = {}): Envelope {
+	if (outcome.timedOut) {
+		return { ok: true, exitCode: -1, timedOut: true, output: "", note: LOCAL_TIMEOUT_NOTE, ...extra };
+	}
+	return { ok: false, exitCode: 1, output: errorMessage(outcome.error), note: EXIT_NOTE[1], ...extra };
+}
+
+/** 失败结局的一行摘要，用于 via 里说明回退原因。 */
+function failureLine(outcome: Failure): string {
+	return outcome.timedOut ? "本地超时" : errorMessage(outcome.error).split("\n")[0];
+}
+
+/**
+ * 在本地截止时间下跑一次 herdr 调用。
+ *
+ * 截止时间是组合 signal，而不是第二条调用路径：execHerdr 本来就跟随 signal 中断，
+ * 所以这里只需把「调用方取消」（重抛）和「我们的截止时间到了」（timedOut）分开。
+ */
+async function attempt<T>(
+	signal: AbortSignal | undefined,
+	timeoutMs: number | undefined,
+	operation: (signal: AbortSignal) => Promise<T>,
+): Promise<Attempt<T>> {
+	const controller = new AbortController();
+	const timer = timeoutMs == null ? null : setTimeout(() => controller.abort(), timeoutMs);
+	const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+	try {
+		return { ok: true, value: await operation(combined) };
+	} catch (error) {
+		if (signal?.aborted === true) throw error;
+		if (controller.signal.aborted) return { ok: false, timedOut: true };
+		return { ok: false, timedOut: false, error };
+	} finally {
+		if (timer !== null) clearTimeout(timer);
+	}
+}
+
+function renderVerbCall(tool: string, args: Record<string, any>, theme: any, context: any) {
 	const component = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
 	let text = theme.fg("toolTitle", theme.bold(`${tool} `));
-	text += theme.fg("accent", args.action || "?");
-	const target = args.target || args.pane || args.tab || args.workspace;
-	if (target) text += theme.fg("muted", ` ${target}`);
-	if (args.name) text += theme.fg("muted", ` ${args.name}`);
-	if (args.kind) text += theme.fg("dim", ` › ${args.kind}`);
+	const target = args.target || args.pane || args.kind || args.workspace;
+	if (target) text += theme.fg("accent", target);
+	if (args.label) text += theme.fg("muted", ` ${args.label}`);
+	if (args.scope) text += theme.fg("dim", ` › ${args.scope}`);
+	if (args.mode) text += theme.fg("dim", ` › ${args.mode}`);
 	if (args.direction) text += theme.fg("dim", ` › ${args.direction}`);
 	if (args.command) text += theme.fg("dim", ` › ${args.command}`);
 	if (args.prompt) text += theme.fg("dim", ` › ${args.prompt}`);
-	if (args.match) text += theme.fg("dim", ` › ${args.match}`);
+	if (args.dryRun === false) text += theme.fg("warning", " › close");
 	component.setText(text);
 	return component;
 }
 
-function renderToolResult(result: any, options: { expanded: boolean; isPartial: boolean }, theme: any) {
-	if (options.isPartial) return new Text(theme.fg("warning", "◌ waiting"), 0, 0);
-	const details = result.details as Record<string, any> | undefined;
+function renderVerbResult(result: any, options: { expanded: boolean; isPartial: boolean }, theme: any) {
+	if (options.isPartial) return new Text(theme.fg("warning", "◌ running"), 0, 0);
 	const content = result.content?.[0];
 	const rawText = content?.type === "text" ? content.text : "";
+	const details = result.details as Envelope | undefined;
 	if (!details) return new Text(rawText, 0, 0);
 
-	if (details.agent) {
-		const agent = details.agent as AgentInfo;
-		return new Text(
-			`${statusDot(theme, agent.agent_status)} ${theme.fg("accent", agentDisplayName(agent))} ${theme.fg("dim", agent.agent_status)}`,
-			0,
-			0,
-		);
-	}
-	if (Array.isArray(details.agents)) {
-		const agents = details.agents as AgentInfo[];
-		return new Text(
-			agents.length
-				? agents
-					.map(
-						(agent) =>
-							`${statusDot(theme, agent.agent_status)} ${theme.fg(agent.focused ? "accent" : "muted", agentDisplayName(agent))} ${theme.fg("dim", agent.agent_status)}`,
-					)
-					.join("\n")
-				: theme.fg("dim", "no agents"),
-			0,
-			0,
-		);
-	}
-	if (details.read) {
-		let text = theme.fg("accent", `▤ ${details.target || details.pane}`);
-		if (options.expanded && rawText) text += `\n${rawText.split("\n").slice(0, 40).map((line: string) => theme.fg("dim", line)).join("\n")}`;
-		return new Text(text, 0, 0);
-	}
-	return new Text(theme.fg("success", `✓ ${details.action || "done"}`), 0, 0);
+	const mark = details.ok
+		? theme.fg("success", "✓")
+		: details.exitCode === -1
+			? theme.fg("warning", "◷")
+			: theme.fg("error", "✗");
+	const code = details.exitCode === 0 ? "" : theme.fg("dim", ` exit=${details.exitCode}`);
+	const lines = rawText.split("\n").filter((line: string) => line.trim() !== "");
+	const head = `${mark}${code} ${theme.fg("muted", lines[0] ?? "")}`;
+	if (!options.expanded) return new Text(head, 0, 0);
+	return new Text([head, ...lines.slice(1).map((line: string) => theme.fg("dim", line))].join("\n"), 0, 0);
 }
 
 export default function (pi: ExtensionAPI) {
 	if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_PANE_ID) return;
 
-	/**
-	 * 本进程最近一次下发到某个 pane 的文本（`run` 的命令、`send_text` 的字面量）。
-	 * wait_output 用它识别“命中行其实就是刚敲下去的命令回显”，而不是命令产生的输出。
-	 */
-	const lastSubmitted = new Map<string, string>();
-
 	async function execHerdr(args: string[], signal?: AbortSignal) {
 		const result = await pi.exec("herdr", args, { signal });
 		if (signal?.aborted || result.killed) throw new Error("Aborted");
 		if (result.code !== 0) {
 			// herdr 把结构化错误写在 stderr（退出码 1）。带上 code，调用方才能区分
-			// timeout / agent_prompt_stalled 这类“没观测到”和真正的失败。
+			// timeout / agent_prompt_stalled 这类「没观测到」和真正的失败。
 			const detail = parseHerdrError(result.stderr) || parseHerdrError(result.stdout);
 			throw herdrError(
 				detail?.message || `herdr ${args.join(" ")} failed with exit code ${result.code}`,
@@ -390,24 +510,11 @@ export default function (pi: ExtensionAPI) {
 		return (await execHerdr(args, signal)).stdout;
 	}
 
-	/**
-	 * 读一次 pane 快照。失败时返回 null —— 读快照失败不能让 wait_output 本身失败。
-	 */
-	async function readPaneSnapshot(
-		paneId: string,
-		source: WaitOutputSource,
-		lines: number | undefined,
-		signal?: AbortSignal,
-	): Promise<string | null> {
-		const args = ["pane", "read", paneId, "--source", source];
-		if (lines != null) args.push("--lines", String(lines));
-		try {
-			return await execHerdrText(args, signal);
-		} catch (error) {
-			if (isAbortError(error, signal)) throw error;
-			return null;
-		}
-	}
+	const textCall = (args: string[], signal?: AbortSignal, timeoutMs?: number) =>
+		attempt(signal, timeoutMs ?? DEFAULT_LOCAL_TIMEOUT, (s) => execHerdrText(args, s));
+
+	const jsonCall = <T>(args: string[], signal?: AbortSignal, timeoutMs?: number) =>
+		attempt(signal, timeoutMs ?? DEFAULT_LOCAL_TIMEOUT, (s) => execHerdrJson<T>(args, s));
 
 	async function getCurrentPane(signal?: AbortSignal): Promise<PaneInfo> {
 		const response = await execHerdrJson<{ result: { pane: PaneInfo } }>(["pane", "current", "--current"], signal);
@@ -427,560 +534,554 @@ export default function (pi: ExtensionAPI) {
 		return response.result.layout;
 	}
 
+	/**
+	 * 把 agent target 解析成 `pane run` 回退需要的完整 pane id。agent 名不是 pane id，
+	 * 侧栏短名也不是，猜一下就会把 prompt 打进错的终端。`agent get` 对活着的名字和承载它
+	 * 的 pane id 都答；全机列表是第二索引，因为自报 agent 可能查不到直接的那一条。
+	 */
+	async function resolveAgentPaneId(target: string, signal?: AbortSignal): Promise<string> {
+		try {
+			const response = await execHerdrJson<{
+				result?: { pane?: { pane_id?: string }; agent?: { pane_id?: string } };
+			}>(["agent", "get", target], signal);
+			const paneId = response.result?.pane?.pane_id || response.result?.agent?.pane_id;
+			if (paneId) return paneId;
+		} catch (error) {
+			if (isAbortError(error, signal)) throw error;
+			// 落到下面的列表扫描：它才是权威索引。
+		}
+		const response = await execHerdrJson<{ result: { agents: AgentInfo[] } }>(["agent", "list"], signal);
+		const match = (response.result.agents || []).find(
+			(agent) => agent.pane_id === target || agent.name === target || agentDisplayName(agent) === target,
+		);
+		if (match?.pane_id) return match.pane_id;
+		throw new Error(
+			`'${target}' 没有解析成完整 pane id（agent get 与 agent list 都查不到），` +
+				"无法确定该往哪个 pane 键入 —— 不猜。先用 herdr_overview 拿到完整 pane id 再发。",
+		);
+	}
+
 	pi.registerTool({
-		name: "herdr_layout",
-		label: "Herdr Layout",
+		name: "herdr_overview",
+		label: "Herdr Overview",
+		outputSchema: envelopeOutputSchema,
 		description:
-			"Create and inspect Herdr terminal topology. Workspaces contain tabs; tabs contain panes. Creating a workspace or tab also creates a root pane, while splitting creates another pane. Layout actions never start an agent or ordinary command. Read pane IDs from results and pass them to herdr_pane or herdr_agent. Creation defaults to the caller's cwd and preserves UI focus. pane_split defaults to the caller's pane and chooses right or down from its geometry.",
-		promptSnippet: "Inspect or create Herdr workspaces, tabs, and pane topology",
+			"盘点：一次拿到自己的位置 + 全机 workspace 拓扑 + 全机 agent 状态（名称/状态/cwd/pane id）。管理其他 agent 的第一步几乎总是它 —— 先看有哪些 agent、谁在忙、谁空着。只读。",
+		promptSnippet: "一次看清 herdr 里有哪些 agent、谁在忙、各自在哪个 pane",
 		promptGuidelines: [
-			"Use herdr_layout, herdr_pane, and herdr_agent only when the user explicitly mentions Herdr or asks to inspect or control Herdr.",
-			"Use herdr_layout to create terminal topology before starting a process or agent. Default to a sibling pane in the caller's current tab and cwd; create a tab or workspace only when requested.",
-			"Read opaque workspace, tab, and pane IDs from herdr_layout results instead of constructing them, and preserve UI focus unless the user asks to switch context.",
+			"要管别的 agent 之前先调 herdr_overview，用结果里的完整 pane id 当后续 target，不要自己拼。",
+			"列表被 limit 截断时会写明隐藏条数 —— 别把截断结果当成「全机就这些」。",
+			"herdr_overview 只读：不切焦点、不下发任何东西。",
 		],
 		parameters: Type.Object({
-			action: StringEnum(
-				[
-					"current",
-					"workspace_list",
-					"workspace_create",
-					"workspace_focus",
-					"tab_list",
-					"tab_create",
-					"tab_focus",
-					"pane_list",
-					"pane_layout",
-					"pane_split",
-				] as const,
-				{ description: "Layout action" },
+			limit: Type.Optional(Type.Integer({ description: `每个列表最多返回多少条，默认 ${OVERVIEW_LIST_LIMIT}` })),
+			workspace: Type.Optional(
+				Type.String({ description: "只看某个 workspace 的拓扑（如 wC）。agent 列表也一并收窄到该 workspace" }),
 			),
-			workspace: Type.Optional(Type.String({ description: "Opaque workspace ID" })),
-			tab: Type.Optional(Type.String({ description: "Opaque tab ID" })),
-			pane: Type.Optional(
-				Type.String({ description: "Opaque source pane ID. Omit for current, pane_layout, or pane_split to use the caller's pane." }),
-			),
-			label: Type.Optional(Type.String({ description: "Label for a new workspace or tab" })),
-			direction: Type.Optional(DirectionEnum),
-			cwd: Type.Optional(Type.String({ description: "Working directory. Defaults to the caller pane's foreground cwd." })),
-			focus: Type.Optional(Type.Boolean({ description: "Change UI focus after creation. Defaults to false." })),
 		}),
-		async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
-			switch (params.action) {
-				case "current": {
-					const pane = await getCurrentPane(signal);
-					return {
-						content: [{ type: "text", text: summarizePane(pane, pane.pane_id) }],
-						details: { action: "current", pane },
-					};
-				}
-				case "workspace_list": {
-					const response = await execHerdrJson<{ result: { workspaces: WorkspaceInfo[] } }>(
-						["workspace", "list"],
-						signal,
-					);
-					const workspaces = response.result.workspaces || [];
-					return {
-						content: [{ type: "text", text: workspaces.length ? workspaces.map(summarizeWorkspace).join("\n") : "No workspaces." }],
-						details: { action: "workspace_list", workspaces },
-					};
-				}
-				case "workspace_create": {
-					const current = await getCurrentPane(signal);
-					const args = ["workspace", "create", "--cwd", params.cwd || current.foreground_cwd || current.cwd || process.cwd()];
-					if (params.label) args.push("--label", params.label);
-					args.push(params.focus === true ? "--focus" : "--no-focus");
-					const response = await execHerdrJson<{
-						result: { workspace: WorkspaceInfo; tab: TabInfo; root_pane: PaneInfo };
-					}>(args, signal);
-					const { workspace, tab, root_pane: rootPane } = response.result;
-					return {
-						content: [{ type: "text", text: `Created workspace ${workspace.workspace_id}, tab ${tab.tab_id}, root pane ${rootPane.pane_id}` }],
-						details: { action: "workspace_create", workspace, tab, pane: rootPane },
-					};
-				}
-				case "workspace_focus": {
-					if (!params.workspace) throw new Error("'workspace' is required for workspace_focus");
-					const response = await execHerdrJson<{ result: { workspace: WorkspaceInfo } }>(
-						["workspace", "focus", params.workspace],
-						signal,
-					);
-					return {
-						content: [{ type: "text", text: `Focused workspace ${response.result.workspace.workspace_id}` }],
-						details: { action: "workspace_focus", workspace: response.result.workspace },
-					};
-				}
-				case "tab_list": {
-					const args = ["tab", "list"];
-					if (params.workspace) args.push("--workspace", params.workspace);
-					const response = await execHerdrJson<{ result: { tabs: TabInfo[] } }>(args, signal);
-					const tabs = response.result.tabs || [];
-					return {
-						content: [{ type: "text", text: tabs.length ? tabs.map(summarizeTab).join("\n") : "No tabs." }],
-						details: { action: "tab_list", tabs },
-					};
-				}
-				case "tab_create": {
-					const current = await getCurrentPane(signal);
-					const args = ["tab", "create", "--workspace", params.workspace || current.workspace_id];
-					args.push("--cwd", params.cwd || current.foreground_cwd || current.cwd || process.cwd());
-					if (params.label) args.push("--label", params.label);
-					args.push(params.focus === true ? "--focus" : "--no-focus");
-					const response = await execHerdrJson<{ result: { tab: TabInfo; root_pane: PaneInfo } }>(args, signal);
-					const { tab, root_pane: rootPane } = response.result;
-					return {
-						content: [{ type: "text", text: `Created tab ${tab.tab_id}, root pane ${rootPane.pane_id}` }],
-						details: { action: "tab_create", tab, pane: rootPane },
-					};
-				}
-				case "tab_focus": {
-					if (!params.tab) throw new Error("'tab' is required for tab_focus");
-					const response = await execHerdrJson<{ result: { tab: TabInfo } }>(["tab", "focus", params.tab], signal);
-					return {
-						content: [{ type: "text", text: `Focused tab ${response.result.tab.tab_id}` }],
-						details: { action: "tab_focus", tab: response.result.tab },
-					};
-				}
-				case "pane_list": {
-					const current = await getCurrentPane(signal);
-					const workspaceId = params.workspace || current.workspace_id;
-					const response = await execHerdrJson<{ result: { panes: PaneInfo[] } }>(
-						["pane", "list", "--workspace", workspaceId],
-						signal,
-					);
-					const panes = response.result.panes || [];
-					return {
-						content: [{ type: "text", text: panes.length ? panes.map((pane) => summarizePane(pane, current.pane_id)).join("\n") : "No panes." }],
-						details: { action: "pane_list", panes, workspaceId },
-					};
-				}
-				case "pane_layout": {
-					const paneId = params.pane || (await getCurrentPane(signal)).pane_id;
-					const layout = await getPaneLayout(paneId, signal);
-					return {
-						content: [{ type: "text", text: JSON.stringify(layout, null, 2) }],
-						details: { action: "pane_layout", layout },
-					};
-				}
-				case "pane_split": {
-					const current = await getCurrentPane(signal);
-					const source = params.pane ? await getPane(params.pane, signal) : current;
-					const direction = params.direction || chooseSplitDirection(await getPaneLayout(source.pane_id, signal), source.pane_id);
-					const cwd = params.cwd || source.foreground_cwd || source.cwd || current.foreground_cwd || current.cwd || process.cwd();
-					const args = ["pane", "split", source.pane_id, "--direction", direction, "--cwd", cwd];
-					args.push(params.focus === true ? "--focus" : "--no-focus");
-					const response = await execHerdrJson<{ result: { pane: PaneInfo } }>(args, signal);
-					const pane = response.result.pane;
-					return {
-						content: [{ type: "text", text: `Created pane ${pane.pane_id} by splitting ${source.pane_id} ${direction}` }],
-						details: { action: "pane_split", pane, sourcePaneId: source.pane_id, direction },
-					};
-				}
+		async execute(_toolCallId, params, signal) {
+			const limit = params.limit ?? OVERVIEW_LIST_LIMIT;
+			// dsh 的参数 spec 没有 minimum，所以这条校验落在 body 里；pi 保持一致好让信封统一。
+			if (!Number.isInteger(limit) || limit < 1) {
+				return envelopeResult(precondition(`--limit must be >= 1 (default ${OVERVIEW_LIST_LIMIT}).`));
+			}
+			// 三次独立读，并行付一次 RTT 而不是三次。
+			const [current, workspaces, agents] = await Promise.all([
+				jsonCall<{ result: { pane: PaneInfo } }>(["pane", "current", "--current"], signal),
+				jsonCall<{ result: { workspaces: WorkspaceInfo[] } }>(["workspace", "list"], signal),
+				jsonCall<{ result: { agents: AgentInfo[] } }>(["agent", "list"], signal),
+			]);
+			const failed: Failure | undefined = [current, workspaces, agents].find(
+				(part): part is Failure => part.ok !== true,
+			);
+			const allWorkspaces = workspaces.ok === true ? workspaces.value.result.workspaces || [] : [];
+			const allAgents = agents.ok === true ? agents.value.result.agents || [] : [];
+			// `agent list` 不接受 --workspace，但每条 agent 记录都带 workspace_id，
+			// 所以收窄是精确的客户端过滤，不需要第二次查询。
+			const scopedWorkspaces = params.workspace
+				? allWorkspaces.filter((workspace) => workspace.workspace_id === params.workspace)
+				: allWorkspaces;
+			const scopedAgents = params.workspace
+				? allAgents.filter((agent) => agent.workspace_id === params.workspace)
+				: allAgents;
+			const output = [
+				"## 我所在的位置",
+				current.ok === true
+					? summarizePane(current.value.result.pane, current.value.result.pane.pane_id)
+					: failureEnvelope(current).output,
+				"## workspace 拓扑",
+				workspaces.ok === true
+					? capList(scopedWorkspaces, limit, "workspaces", summarizeWorkspace)
+					: failureEnvelope(workspaces).output,
+				params.workspace ? `## agent（workspace ${params.workspace}）` : "## 全机 agent",
+				agents.ok === true
+					? capList(scopedAgents, limit, "agents", summarizeAgent)
+					: failureEnvelope(agents).output,
+			].join("\n");
+			// 本地超时不是 herdr 错误，但确实少了一段；把盘点报成 ok 会让 manager
+			// 以为自己看全了整支舰队。
+			if (failed === undefined) return envelopeResult({ ok: true, exitCode: 0, output });
+			if (failed.timedOut) {
+				return envelopeResult({
+					ok: false,
+					exitCode: -1,
+					timedOut: true,
+					output,
+					note: "盘点有部分超时：本地等待超时只说明没观测到，不等于 herdr 出错。重跑一次，或缩小 limit 再试。",
+				});
 			}
+			return envelopeResult({ ok: false, exitCode: 1, output, note: EXIT_NOTE[1] });
 		},
 		renderCall(args, theme, context) {
-			return renderToolCall("herdr_layout", args, theme, context);
+			return renderVerbCall("herdr_overview", args, theme, context);
 		},
 		renderResult(result, options, theme) {
-			return renderToolResult(result, options, theme);
+			return renderVerbResult(result, options, theme);
 		},
 	});
 
 	pi.registerTool({
-		name: "herdr_pane",
-		label: "Herdr Pane",
+		name: "herdr_read",
+		label: "Herdr Read",
+		outputSchema: envelopeOutputSchema,
 		description:
-			"Control a raw Herdr terminal pane. Use for shells, tests, servers, builds, logs, and other ordinary processes: run a command, read output, wait for matching output, send literal text or terminal keys, inspect, or close. Pane actions target opaque pane IDs and do not validate agent identity or interpret agent lifecycle. Use herdr_agent instead when controlling a recognized coding agent. Read output is truncated to 2000 lines or 50KB.",
-		promptSnippet: "Run and inspect ordinary commands in Herdr terminal panes",
+			"读屏：看某个 pane（或它里面的 agent）当前输出。盯梢一个 agent 在干什么、卡在哪，用它。target 用完整限定 pane id（如 wC:p77）；scope=agent 走 agent 语义视图，pane 走裸终端视图。只读。默认 digest 模式：只回「前段命中的审批/报错行 + 尾部 30 行」，省上下文；要看整段传 mode=\"raw\"。",
+		promptSnippet: "读取某个 pane 或 agent 的当前输出（默认压缩成信号行 + 尾部）",
 		promptGuidelines: [
-			"Use herdr_pane for ordinary commands and raw terminal control; use herdr_agent for coding-agent prompts, lifecycle waits, reads, and interactive keys.",
-			"Use herdr_pane wait_output for tests, servers, builds, and watchers. It searches existing output immediately; use recent-unwrapped for logs and transcripts.",
-			"wait_output reports a timeout as matched:false with the pane tail instead of raising an error: a timeout means the pattern never appeared, not that the command failed.",
-			"Pick a wait_output pattern that only appears in the command output. Patterns that also occur in the command you sent (script names, function names, marker constants) match the echoed input line and can report success before the command produces anything; echoedInput flags such a hit.",
-			"Never use a shell prompt (❯, $, \\$) as a wait_output pattern; it is always present and therefore meaningless.",
-			"Do not close a Herdr pane you did not create unless the user explicitly asks. herdr_pane always refuses to close the pane running the current pi process.",
+			"读屏先走默认 scope=agent；pane 里没有 herdr 可识别的 agent 时会自动回退到 pane 视图，via 会说明走了哪条。",
+			"默认 digest 已经够判断「在干什么/卡在哪」；确信需要逐行引用原文时才传 mode=\"raw\"。",
+			"失败不会被压缩：错误原文本身就是证据。",
 		],
 		parameters: Type.Object({
-			action: StringEnum(["get", "run", "read", "wait_output", "send_text", "send_keys", "close"] as const, {
-				description: "Raw pane action",
-			}),
-			pane: Type.String({ description: "Opaque pane ID returned by herdr_layout" }),
-			command: Type.Optional(Type.String({ description: "Shell command to submit atomically with Enter for run" })),
-			text: Type.Optional(Type.String({ description: "Literal text to send without Enter for send_text" })),
-			keys: Type.Optional(
-				Type.Array(Type.String(), { description: "Logical terminal keys for send_keys, such as esc, enter, up, or ctrl+c" }),
-			),
-			match: Type.Optional(
-				Type.String({
-					description:
-						"Pattern for wait_output. Patterns containing regex metacharacters (| ( ) [ ] { } ^ $ * + ? \\) are treated as Rust regular expressions unless regex is explicitly false",
+			target: Type.String({ description: "完整限定 pane id（w1B:pF），或唯一 agent 名" }),
+			scope: Type.Optional(
+				StringEnum(["agent", "pane"] as const, {
+					description: "默认 agent；pane 里没有可识别 agent 时用 pane",
 				}),
 			),
-			regex: Type.Optional(
-				Type.Boolean({ description: "Force match to be a literal string (false) or a Rust regular expression (true)" }),
-			),
 			source: Type.Optional(ReadSourceEnum),
-			lines: Type.Optional(Type.Integer({ minimum: 1, description: "Rendered terminal rows to read or search" })),
-			format: Type.Optional(OutputFormatEnum),
-			raw: Type.Optional(
-				Type.Boolean({ description: "Keep ANSI escapes while reading (read) or matching (wait_output)" }),
+			lines: Type.Optional(Type.Integer({ minimum: 1, description: "只取尾部 N 行（默认 2000 行 / 50KB 封顶）" })),
+			mode: Type.Optional(ReadModeEnum),
+			tail: Type.Optional(Type.Integer({ minimum: 1, description: `digest 保留多少行尾部，默认 ${READ_TAIL_LINES}` })),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const scope = params.scope ?? "agent";
+			const source = params.source ?? "recent-unwrapped";
+			const lines = params.lines === undefined ? [] : ["--lines", String(params.lines)];
+			const build = (view: "agent" | "pane") =>
+				view === "agent"
+					? ["agent", "read", params.target, "--source", source, ...lines]
+					: ["pane", "read", params.target, "--source", source, ...lines];
+			const first = await textCall(build(scope), signal);
+			let result: Attempt<string> = first;
+			let via: string = scope;
+			if (first.ok !== true && scope === "agent") {
+				// 这个 pane 里没有 herdr 认的 agent：回退到裸终端视图，并说清哪条路给出了文字。
+				result = await textCall(build("pane"), signal);
+				via = `pane（agent 视图不可用：${failureLine(first)}）`;
+			}
+			const mode = params.mode ?? READ_MODE_DEFAULT;
+			// 失败从不压缩：错误文本本身就是证据。
+			if (result.ok !== true) return envelopeResult(failureEnvelope(result, { via }));
+			const output = formatOutput(result.value).trim();
+			if (mode === "raw") return envelopeResult({ ok: true, exitCode: 0, output, via });
+			return envelopeResult({
+				ok: true,
+				exitCode: 0,
+				output: digestRead(output, params.tail ?? READ_TAIL_LINES),
+				via: `${via} · digest`,
+			});
+		},
+		renderCall(args, theme, context) {
+			return renderVerbCall("herdr_read", args, theme, context);
+		},
+		renderResult(result, options, theme) {
+			return renderVerbResult(result, options, theme);
+		},
+	});
+
+	pi.registerTool({
+		name: "herdr_wait",
+		label: "Herdr Wait",
+		outputSchema: envelopeOutputSchema,
+		description:
+			"等某个 agent 进入指定状态（默认 idle/done/blocked）。盯梢的关键原语：下发任务后等它落定。注意超时只表示「没观测到」，不是失败 —— 不要据此重发任务，先 herdr_read 看实际情况。",
+		promptSnippet: "等待某个 agent 进入 idle/done/blocked",
+		promptGuidelines: [
+			"下发任务以后用 herdr_wait 等它落定，而不是反复 herdr_read 轮询。",
+			"等待超时只说明给定时间内没观测到那个状态，不等于对方失败，也不等于任务没送到。",
+		],
+		parameters: Type.Object({
+			target: Type.String({ description: "完整限定 pane id，或唯一 agent 名" }),
+			until: Type.Optional(Type.Array(StatusEnum, { description: "要等的状态，默认 idle/done/blocked" })),
+			timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "herdr 侧等待上限，默认由 herdr 决定" })),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const until = (params.until ?? []).flatMap((state) => ["--until", state]);
+			const timeout = params.timeoutMs === undefined ? [] : ["--timeout", String(params.timeoutMs)];
+			const local = (params.timeoutMs ?? WAIT_DEFAULT_TIMEOUT) + WAIT_LOCAL_MARGIN;
+			const result = await jsonCall<{ result: { agent: AgentInfo } }>(
+				["agent", "wait", params.target, ...until, ...timeout],
+				signal,
+				local,
+			);
+			if (result.ok === true) {
+				return envelopeResult({
+					ok: true,
+					exitCode: 0,
+					output: `Agent settled: ${summarizeAgent(result.value.result.agent)}`,
+				});
+			}
+			if (result.timedOut) return envelopeResult(failureEnvelope(result));
+			if (!isHerdrTimeout(result.error)) return envelopeResult(failureEnvelope(result));
+			// herdr 把等待超时也报成结构化错误（非零退出）。它的意思是「没观测到」，
+			// 所以保留失败退出码，但把这个「不意味着什么」说清楚。
+			return envelopeResult({
+				ok: false,
+				exitCode: 1,
+				output: failureEnvelope(result).output,
+				note:
+					"等待超时：给定时间内没观测到目标状态。这不等于对方失败、也不等于任务没送到 —— " +
+					"先 herdr_read 看它实际在做什么，再决定要不要重发。",
+			});
+		},
+		renderCall(args, theme, context) {
+			return renderVerbCall("herdr_wait", args, theme, context);
+		},
+		renderResult(result, options, theme) {
+			return renderVerbResult(result, options, theme);
+		},
+	});
+
+	pi.registerTool({
+		name: "herdr_prompt",
+		label: "Herdr Prompt",
+		outputSchema: envelopeOutputSchema,
+		description:
+			"给另一个 agent 下发一段 prompt（调度）。先试 agent prompt（语义路径）；若对方是自报状态的 dsh-tui，herdr 会回 agent_not_ready，此时自动回退成 pane run 直接键入。返回的 via 会说明走了哪条路。「已送出」不等于「已开始干活」—— 要确认请配 herdr_wait 或 herdr_read。",
+		promptSnippet: "给另一个 agent 下发任务（自动回退到直接键入）",
+		promptGuidelines: [
+			"herdr_prompt 默认发完就走（不等落定）；要等它进入稳定状态请传 wait=true，或另外调 herdr_wait。",
+			"目标正在 working 时默认拒绝下发（那是插队，会打断它手上的任务）：先 herdr_wait 等它落定；确实要插队才传 force=true。",
+			"如果失败信封说 agent_blocked，说明 herdr 在发送任何输入之前就拒绝了：先 herdr_read 看清弹窗内容并问用户，不要重复下发。",
+			"「已送出」不等于「已开始干活」—— 用 herdr_wait / herdr_read 确认。",
+		],
+		parameters: Type.Object({
+			target: Type.String({ description: "完整限定 pane id，或 herdr 命名并激活的 agent 名" }),
+			prompt: Type.String({ description: "要下发的完整任务文本" }),
+			wait: Type.Optional(Type.Boolean({ description: "true 时等它进入稳定状态（agent prompt 语义）；默认发了就走" })),
+			force: Type.Optional(
+				Type.Boolean({ description: "目标正在 working 时，默认拒绝下发（插队会打断它）；确实要插队传 true" }),
 			),
-			timeout: Type.Optional(Type.Integer({ minimum: 1, description: "Wait timeout in milliseconds; omitted means indefinite" })),
 		}),
-		async execute(_toolCallId, params, signal, onUpdate, _ctx) {
-			switch (params.action) {
-				case "get": {
-					const pane = await getPane(params.pane, signal);
-					return {
-						content: [{ type: "text", text: summarizePane(pane) }],
-						details: { action: "get", pane },
-					};
-				}
-				case "run": {
-					if (!params.command) throw new Error("'command' is required for run");
-					// pane run/send-text/send-keys report success with empty stdout, so only the exit code is meaningful.
-					await execHerdr(["pane", "run", params.pane, params.command], signal);
-					lastSubmitted.set(params.pane, params.command);
-					return {
-						content: [{ type: "text", text: `Submitted command to pane ${params.pane}` }],
-						details: { action: "run", pane: params.pane, command: params.command },
-					};
-				}
-				case "read": {
-					const args = ["pane", "read", params.pane, "--source", params.source || "recent-unwrapped"];
-					if (params.lines != null) args.push("--lines", String(params.lines));
-					if (params.format) args.push("--format", params.format);
-					if (params.raw) args.push("--raw");
-					const output = await execHerdrText(args, signal);
-					return {
-						content: [{ type: "text", text: formatOutput(output) }],
-						details: { action: "read", pane: params.pane, read: true, source: params.source || "recent-unwrapped" },
-					};
-				}
-				case "wait_output": {
-					if (!params.match) throw new Error("'match' is required for wait_output");
-					if (params.source === "detection") throw new Error("wait_output does not support the detection source; use read");
-					const startedAt = Date.now();
-					const source: WaitOutputSource = (params.source as WaitOutputSource) || "recent-unwrapped";
-					// 未显式指定 regex 时，含正则元字符的 pattern 按正则解释：字面量语义下
-					// `a|b` / `log \$` 永远不可能命中，只会白等满 timeout。
-					const matchMode: "literal" | "regex" =
-						params.regex === true
-							? "regex"
-							: params.regex === false
-								? "literal"
-								: REGEX_METACHARS.test(params.match)
-									? "regex"
-									: "literal";
-					const notes: string[] = [];
-					if (matchMode === "literal" && REGEX_METACHARS.test(params.match)) {
-						notes.push(
-							`注意：${JSON.stringify(params.match)} 含正则元字符但按字面量匹配，很可能永远无法命中；需要正则请设 regex: true。`,
-						);
-					}
-					onUpdate?.({
-						content: [{ type: "text", text: `Waiting for output in ${params.pane}...` }],
-						details: { action: "wait_output", pane: params.pane, waiting: true },
-					});
-					const args = ["pane", "wait-output", params.pane, matchMode === "regex" ? "--regex" : "--match", params.match];
-					args.push("--source", source);
-					if (params.lines != null) args.push("--lines", String(params.lines));
-					if (params.timeout != null) args.push("--timeout", String(params.timeout));
-					if (params.raw) args.push("--raw");
-					let response: { result: WaitOutputResult } | null;
-					try {
-						response = await execHerdrJson<{ result: WaitOutputResult }>(args, signal);
-					} catch (error) {
-						if (!isHerdrTimeout(error)) throw error;
-						response = null;
-					}
-					if (response === null) {
-						// 超时是“没观测到”，不是失败：返回观测事实（含 pane 尾部输出）让调用方自己判断。
-						const tail = await readPaneSnapshot(params.pane, source, params.lines, signal);
-						const waitedMs = Date.now() - startedAt;
-						return {
-							content: [
-								{
-									type: "text",
-									text: [
-										`未匹配：${JSON.stringify(params.match)}（模式=${matchMode}, source=${source}）在 ${waitedMs}ms 内未出现。`,
-										"这既不表示命令失败，也不表示命令完成，只表示这个 pattern 没有出现。",
-										...notes,
-										tail ? `当前 pane 尾部输出：\n${formatOutput(tail)}` : "（未能读取 pane 尾部输出）",
-									].join("\n"),
-								},
-							],
-							details: {
-								action: "wait_output",
-								pane: params.pane,
-								matched: false,
-								waitedMs,
-								matchMode,
-								source,
-								tail,
-							},
-						};
-					}
-					const matched = response.result;
-					const output = matched.read?.text || matched.matched_line;
-					// 命中行可能来自刚下发的命令回显（`❯ <命令>`）而不是命令产生的输出，
-					// 回显在命令还没跑完时就已经存在。本进程自己记录的下发内容是最可靠的事实依据。
-					const submitted = lastSubmitted.get(params.pane);
-					const echoedInput = !!submitted && matched.matched_line.includes(submitted);
-					if (echoedInput) {
-						notes.push(
-							"注意：命中的是刚下发的命令回显行（❯ 后面那段），不是命令产生的输出；命令可能还没跑完。要等真正的输出，请改用只会出现在输出里的 pattern。",
-						);
-					}
-					return {
-						content: [
-							{
-								type: "text",
-								text: [...notes, `Matched: ${matched.matched_line}`, "", formatOutput(output)].join("\n"),
-							},
-						],
-						details: {
-							action: "wait_output",
-							pane: params.pane,
-							matched: true,
-							matchedLine: matched.matched_line,
-							matchMode,
-							source,
-							echoedInput,
-							elapsedMs: Date.now() - startedAt,
-						},
-					};
-				}
-				case "send_text": {
-					if (!params.text) throw new Error("'text' is required for send_text");
-					await execHerdr(["pane", "send-text", params.pane, params.text], signal);
-					lastSubmitted.set(params.pane, params.text);
-					return {
-						content: [{ type: "text", text: `Sent literal text to pane ${params.pane}` }],
-						details: { action: "send_text", pane: params.pane },
-					};
-				}
-				case "send_keys": {
-					if (!params.keys?.length) throw new Error("'keys' is required for send_keys");
-					await execHerdr(["pane", "send-keys", params.pane, ...params.keys], signal);
-					return {
-						content: [{ type: "text", text: `Sent ${params.keys.join(" ")} to pane ${params.pane}` }],
-						details: { action: "send_keys", pane: params.pane, keys: params.keys },
-					};
-				}
-				case "close": {
-					const current = await getCurrentPane(signal);
-					if (params.pane === current.pane_id) throw new Error("Refusing to close the pane pi is running in.");
-					await execHerdrJson(["pane", "close", params.pane], signal);
-					return {
-						content: [{ type: "text", text: `Closed pane ${params.pane}` }],
-						details: { action: "close", pane: params.pane },
-					};
-				}
+		async execute(_toolCallId, params, signal) {
+			const self = process.env.HERDR_PANE_ID;
+			// 先探一下：状态决定插队保护，pane id 让自身检查能抓到「名字与自己的 pane 不同」的目标。
+			const probe = await jsonCall<{ result: { agent: AgentInfo } }>(["agent", "get", params.target], signal);
+			const agent = probe.ok === true ? probe.value.result.agent : undefined;
+			const pane = agent?.pane_id;
+			const status = agent?.agent_status;
+			const unresolved =
+				probe.ok === true && pane !== undefined
+					? undefined
+					: "无法把 target 解析成完整 pane id（agent get 失败或输出未识别），下面的回退将不可用。";
+			// 往自己的 pane 里键入等于给自己喂输入，会打断正在进行的这一轮。
+			if (self !== undefined && (params.target === self || pane === self)) return envelopeResult(refusal(SELF_PANE_REFUSAL));
+			// 插队正在 working 的 agent：managing-agents 的纪律，这里做成机械约束。
+			if (PROMPT_GUARD_ON && status === "working" && params.force !== true) {
+				return envelopeResult({
+					ok: false,
+					exitCode: 2,
+					output: `目标 ${pane} 当前状态：working。`,
+					note:
+						"它正在干活，现在下发等于插队，会打断它手上的任务。先 herdr_wait 等它落定再发；" +
+						"确实要插队就显式传 force=true。",
+				});
+			}
+			// herdr CLI 只有 --wait，没有 --no-wait。
+			const waitFlag = params.wait === true ? ["--wait"] : [];
+			const semantic = await textCall(["agent", "prompt", params.target, params.prompt, ...waitFlag], signal);
+			if (semantic.ok === true) {
+				return envelopeResult({
+					ok: true,
+					exitCode: 0,
+					output: semantic.value.trim(),
+					via: "agent prompt",
+					...(unresolved === undefined ? {} : { note: unresolved }),
+				});
+			}
+			// 本地超时：不知道有没有送达，但也不是 herdr 拒绝。
+			if (semantic.timedOut) return envelopeResult(failureEnvelope(semantic, { via: "agent prompt" }));
+			// 目标卡在审批/提问弹窗：herdr 在发送任何输入之前就拒绝了，确定没下发。
+			// 这与 stalled 相反 —— 重试必然同样失败，必须先看清界面。
+			if (isPromptBlocked(semantic.error)) {
+				return envelopeResult({
+					ok: false,
+					exitCode: 2,
+					output: errorMessage(semantic.error),
+					via: "agent prompt",
+					note:
+						`${params.target} 处于 blocked（等待审批或回答），herdr 在发送任何输入前就拒绝了本次 prompt。` +
+						"先用 herdr_read 看清阻塞的界面，向用户确认怎么答，再用 herdr_prompt / herdr_run 回应；不要重复下发。",
+				});
 			}
+			// submission accepted 之后没观测到 working/blocked：prompt 已经下发了，
+			// 这是启发式，不能当成下发失败。
+			if (isPromptStalled(semantic.error)) {
+				const observed = /status is (\w+)/.exec(errorMessage(semantic.error))?.[1];
+				return envelopeResult({
+					ok: true,
+					exitCode: 0,
+					output:
+						`Prompt 已下发到 ${params.target}（submission accepted），但 5s 内未观测到进入 working/blocked` +
+						(observed ? `（当前状态 ${observed}）` : "") +
+						"。",
+					via: "agent prompt",
+					note: "不要再下发一次；用 herdr_read 确认它是否已开始工作。",
+				});
+			}
+			const semanticMessage = errorMessage(semantic.error);
+			// herdr 只接受 agent prompt 给「它自己命名并激活」的 agent；自报状态的 agent
+			// （dsh-tui）会回 agent_not_ready。文案匹配兜住不带结构化 code 的版本。
+			if (!/agent_not_ready|not an active named agent/i.test(semanticMessage)) {
+				return envelopeResult(failureEnvelope(semantic, { via: "agent prompt" }));
+			}
+			// pane run 不收裸 agent 名，而往猜出来的 pane 里键入比直接失败更糟。
+			const resolved = await attempt(signal, DEFAULT_LOCAL_TIMEOUT, (s) => resolveAgentPaneId(params.target, s));
+			if (resolved.ok !== true) {
+				return envelopeResult({
+					ok: false,
+					exitCode: 2,
+					output: resolved.timedOut ? semanticMessage : errorMessage(resolved.error),
+					note:
+						"agent prompt 不可用（对方是自报 agent），而 target 又不是完整 pane id，" +
+						"无法确定该往哪个 pane 键入 —— 不猜。先用 herdr_overview 或 herdr_read 拿到完整 pane id 再发。",
+				});
+			}
+			const paneId = resolved.value;
+			const fallbackVia = `pane run ${paneId}（agent prompt 不可用：对方是自报 agent，非 herdr 命名 agent）`;
+			const typed = await textCall(["pane", "run", paneId, params.prompt], signal);
+			if (typed.ok !== true) return envelopeResult(failureEnvelope(typed, { via: fallbackVia }));
+			return envelopeResult({
+				ok: true,
+				exitCode: 0,
+				output: `Submitted prompt to pane ${paneId}`,
+				via: fallbackVia,
+			});
 		},
 		renderCall(args, theme, context) {
-			return renderToolCall("herdr_pane", args, theme, context);
+			return renderVerbCall("herdr_prompt", args, theme, context);
 		},
 		renderResult(result, options, theme) {
-			return renderToolResult(result, options, theme);
+			return renderVerbResult(result, options, theme);
 		},
 	});
 
 	pi.registerTool({
-		name: "herdr_agent",
-		label: "Herdr Agent",
+		name: "herdr_run",
+		label: "Herdr Run",
+		outputSchema: envelopeOutputSchema,
 		description:
-			"Control a recognized coding agent occupying an existing Herdr pane. Starting requires an available interactive shell pane created through herdr_layout and never creates or changes layout. Agent targets are unique live names or the pane ID currently hosting the agent, never terminal IDs or bare kind labels. Use prompt, wait, read, and send_keys instead of raw pane input. Lifecycle states are working, blocked, done, idle, and unknown; prompt and wait default to the first settled idle, done, or blocked state. Read output is truncated to 2000 lines or 50KB.",
-		promptSnippet: "Start, prompt, wait for, read, and interact with coding agents in Herdr",
+			"在指定 pane 里跑一条命令（裸终端，原子下发：文本 + Enter）。用来在别的 pane 起服务、跑脚本。成功 = 退出 0 且 stdout 为空，别期待回显信封；要确认结果用 herdr_read 或 herdr_wait。",
+		promptSnippet: "在另一个 pane 里原子下发一条命令",
 		promptGuidelines: [
-			"Use herdr_agent for recognized coding agents. Use herdr_layout to create an available shell pane first; herdr_agent start never creates or moves terminal layout.",
-			"For normal helper work, use herdr_layout pane_split, then herdr_agent start, herdr_agent prompt with wait enabled, and herdr_agent read. Use herdr_pane only for ordinary processes or intentional raw terminal control.",
-			"Treat herdr_agent idle and done as ready states, blocked as requiring inspection or input, and unknown as uncertain rather than completed. CLI reads do not mark done work as seen.",
-			"When a prompt is rejected with agent_blocked, nothing was sent and retrying will fail the same way: inspect the blocking UI with get and read, and ask the operator before answering it.",
-			"If herdr_agent read cannot recover a full alternate-screen response after increasing lines, ask the agent to write its complete response to a temporary Markdown file and return the path, then read that file directly.",
+			"herdr_run 只负责把命令送进 pane，不负责等它跑完；确认结果用 herdr_read 或 herdr_wait。",
+			"不要用 herdr_run 往自己所在的 pane 里下发命令：那会打断你正在进行的这一轮。",
+			"要驱动的是 coding agent 而不是普通 shell 时，用 herdr_prompt。",
 		],
 		parameters: Type.Object({
-			action: StringEnum(["list", "get", "start", "prompt", "wait", "read", "send_keys", "focus", "rename"] as const, {
-				description: "Agent lifecycle action",
-			}),
-			target: Type.Optional(Type.String({ description: "Unique live agent name or pane ID currently hosting the agent" })),
-			pane: Type.Optional(Type.String({ description: "Existing available shell pane ID for start" })),
-			name: Type.Optional(
-				Type.String({
-					pattern: "^[a-z][a-z0-9_-]{0,31}$",
-					description: "Unique agent name for start or replacement name for rename",
-				}),
+			pane: Type.String({ description: "完整限定 pane id（w1B:pF）" }),
+			command: Type.String({ description: "要执行的命令" }),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const self = process.env.HERDR_PANE_ID;
+			if (self !== undefined && params.pane === self) return envelopeResult(refusal(SELF_PANE_REFUSAL));
+			const result = await textCall(["pane", "run", params.pane, params.command], signal);
+			// 这里的成功是退出 0 且 stdout 为空；要求信封会把已经送达的命令报成失败。
+			if (result.ok !== true) return envelopeResult(failureEnvelope(result));
+			return envelopeResult({ ok: true, exitCode: 0, output: `Submitted command to pane ${params.pane}` });
+		},
+		renderCall(args, theme, context) {
+			return renderVerbCall("herdr_run", args, theme, context);
+		},
+		renderResult(result, options, theme) {
+			return renderVerbResult(result, options, theme);
+		},
+	});
+
+	pi.registerTool({
+		name: "herdr_create",
+		label: "Herdr Create",
+		outputSchema: envelopeOutputSchema,
+		description:
+			"开新位置：workspace / tab / 兄弟 pane。默认不动焦点（不加 --focus），避免把用户正在看的上下文切走。返回的新 pane id 才是后续操作要用的句柄。",
+		promptSnippet: "创建 workspace / tab / 兄弟 pane，并拿回新 pane id",
+		promptGuidelines: [
+			"开新位置用 herdr_create；返回的 pane id 是后续 herdr_run / herdr_prompt 的句柄，别自己拼。",
+			"默认不切焦点：用户正在看的上下文保持不变。确实要切才传 focus=true。",
+			"pane 是相对调用者自己的 pane 切分；要在别的 pane 里切，先切焦点或改用 workspace/tab。",
+		],
+		parameters: Type.Object({
+			kind: CreateKindEnum,
+			workspace: Type.Optional(Type.String({ description: "tab 的目标 workspace（默认当前）。kind=workspace/pane 时忽略" })),
+			label: Type.Optional(Type.String({ description: "workspace/tab 的标签" })),
+			cwd: Type.Optional(Type.String({ description: "新位置的工作目录" })),
+			direction: Type.Optional(DirectionEnum),
+			focus: Type.Optional(Type.Boolean({ description: "是否把焦点切过去；默认 false" })),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const focusFlag = params.focus === true ? "--focus" : "--no-focus";
+			const current = await attempt(signal, DEFAULT_LOCAL_TIMEOUT, (s) => getCurrentPane(s));
+			if (current.ok !== true) return envelopeResult(failureEnvelope(current));
+			const here = current.value;
+			const cwd = params.cwd || here.foreground_cwd || here.cwd || process.cwd();
+			if (params.kind === "workspace") {
+				const args = ["workspace", "create", "--cwd", cwd];
+				if (params.label !== undefined) args.push("--label", params.label);
+				args.push(focusFlag);
+				const created = await jsonCall<{
+					result: { workspace: WorkspaceInfo; tab: { tab_id: string }; root_pane: PaneInfo };
+				}>(args, signal);
+				if (created.ok !== true) return envelopeResult(failureEnvelope(created));
+				const { workspace, tab, root_pane: rootPane } = created.value.result;
+				return envelopeResult({
+					ok: true,
+					exitCode: 0,
+					output: `Created workspace ${workspace.workspace_id}, tab ${tab.tab_id}, root pane ${rootPane.pane_id}`,
+				});
+			}
+			if (params.kind === "tab") {
+				const args = ["tab", "create", "--workspace", params.workspace || here.workspace_id, "--cwd", cwd];
+				if (params.label !== undefined) args.push("--label", params.label);
+				args.push(focusFlag);
+				const created = await jsonCall<{ result: { tab: { tab_id: string }; root_pane: PaneInfo } }>(args, signal);
+				if (created.ok !== true) return envelopeResult(failureEnvelope(created));
+				const { tab, root_pane: rootPane } = created.value.result;
+				return envelopeResult({
+					ok: true,
+					exitCode: 0,
+					output: `Created tab ${tab.tab_id}, root pane ${rootPane.pane_id}`,
+				});
+			}
+			// 切分是相对调用者自己的 pane：--workspace 在这里没有意义。
+			const layout = await attempt(signal, DEFAULT_LOCAL_TIMEOUT, (s) => getPaneLayout(here.pane_id, s));
+			const direction =
+				params.direction || chooseSplitDirection(layout.ok === true ? layout.value : { panes: [] }, here.pane_id);
+			const args = ["pane", "split", here.pane_id, "--direction", direction, "--cwd", cwd, focusFlag];
+			const created = await jsonCall<{ result: { pane: PaneInfo } }>(args, signal);
+			if (created.ok !== true) return envelopeResult(failureEnvelope(created));
+			return envelopeResult({
+				ok: true,
+				exitCode: 0,
+				output: `Created pane ${created.value.result.pane.pane_id} by splitting ${here.pane_id} ${direction}`,
+			});
+		},
+		renderCall(args, theme, context) {
+			return renderVerbCall("herdr_create", args, theme, context);
+		},
+		renderResult(result, options, theme) {
+			return renderVerbResult(result, options, theme);
+		},
+	});
+
+	pi.registerTool({
+		name: "herdr_agent_start",
+		label: "Herdr Agent Start",
+		outputSchema: envelopeOutputSchema,
+		description:
+			"在一个已经停在交互提示符的 shell pane 里启动 coding agent。它不创建 pane、不移动布局 —— 要新位置先用 herdr_create。注意 kind 列表里没有 dsh-tui（dsh-tui 靠自报被识别，不由 agent start 起出来）。",
+		promptSnippet: "在空闲 shell pane 里启动一个 coding agent",
+		promptGuidelines: [
+			"先 herdr_create 拿到一个停在提示符的 shell pane，再 herdr_agent_start —— 它不会创建 pane，也不会移动布局。",
+			"name 必须是唯一的小写名字（^[a-z][a-z0-9_-]{0,31}$）；后续 prompt / wait / read 都用这个名字或它的 pane id。",
+			"kind 只接受 herdr 认识的那几种；启动失败时先看 kind 是否在枚举里。",
+		],
+		parameters: Type.Object({
+			name: Type.String({ description: "给这个 agent 的唯一名字（^[a-z][a-z0-9_-]{0,31}$）" }),
+			kind: AgentKindEnum,
+			pane: Type.String({ description: "承载它的完整限定 pane id，必须是停在提示符的 shell pane" }),
+			timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "启动等待上限" })),
+			agentArgs: Type.Optional(
+				Type.Array(Type.String(), { description: "原样传给 agent 的额外参数（放在 -- 之后）。dsh manager 面没有这个参数，pi 侧保留" }),
 			),
-			kind: Type.Optional(AgentKindEnum),
-			agentArgs: Type.Optional(Type.Array(Type.String(), { description: "Native agent arguments passed unchanged after -- for start" })),
-			prompt: Type.Optional(Type.String({ description: "Prompt text submitted atomically with Enter" })),
-			wait: Type.Optional(Type.Boolean({ description: "Wait for lifecycle settlement after prompt. Defaults to true." })),
-			until: Type.Optional(Type.Array(StatusEnum, { description: "Accepted lifecycle states for prompt with wait or wait; defaults to idle, done, or blocked" })),
-			timeout: Type.Optional(Type.Integer({ minimum: 1, description: "Timeout in milliseconds; omitted means indefinite" })),
-			source: Type.Optional(ReadSourceEnum),
-			lines: Type.Optional(Type.Integer({ minimum: 1, description: "Rendered terminal rows to read" })),
-			format: Type.Optional(OutputFormatEnum),
-			keys: Type.Optional(Type.Array(Type.String(), { description: "Logical UI keys such as esc, enter, up, or ctrl+c" })),
-			clearName: Type.Optional(Type.Boolean({ description: "Clear the current agent name for rename" })),
 		}),
-		async execute(_toolCallId, params, signal, onUpdate, _ctx) {
-			switch (params.action) {
-				case "list": {
-					const response = await execHerdrJson<{ result: { agents: AgentInfo[] } }>(["agent", "list"], signal);
-					const agents = response.result.agents || [];
-					return {
-						content: [{ type: "text", text: agents.length ? agents.map(summarizeAgent).join("\n") : "No agents." }],
-						details: { action: "list", agents },
-					};
-				}
-				case "get": {
-					if (!params.target) throw new Error("'target' is required for get");
-					const response = await execHerdrJson<{ result: { agent: AgentInfo } }>(["agent", "get", params.target], signal);
-					return {
-						content: [{ type: "text", text: summarizeAgent(response.result.agent) }],
-						details: { action: "get", agent: response.result.agent },
-					};
-				}
-				case "start": {
-					if (!params.name) throw new Error("'name' is required for start");
-					if (!params.kind) throw new Error("'kind' is required for start");
-					if (!params.pane) throw new Error("'pane' is required for start");
-					if (params.timeout != null && (params.timeout <= 3000 || params.timeout > 300000)) {
-						throw new Error("start timeout must be greater than 3000ms and at most 300000ms");
-					}
-					const args = ["agent", "start", params.name, "--kind", params.kind, "--pane", params.pane];
-					if (params.timeout != null) args.push("--timeout", String(params.timeout));
-					if (params.agentArgs?.length) args.push("--", ...params.agentArgs);
-					onUpdate?.({
-						content: [{ type: "text", text: `Starting ${params.kind} as ${params.name} in ${params.pane}...` }],
-						details: { action: "start", waiting: true },
-					});
-					const response = await execHerdrJson<{ result: { agent: AgentInfo } }>(args, signal);
-					return {
-						content: [{ type: "text", text: `Started ${summarizeAgent(response.result.agent)}` }],
-						details: { action: "start", agent: response.result.agent },
-					};
-				}
-				case "prompt": {
-					if (!params.target) throw new Error("'target' is required for prompt");
-					if (!params.prompt) throw new Error("'prompt' is required for prompt");
-					const shouldWait = params.wait !== false;
-					if (!shouldWait && params.until?.length) throw new Error("'until' requires wait for prompt");
-					if (!shouldWait && params.timeout != null) throw new Error("'timeout' requires wait for prompt");
-					const args = ["agent", "prompt", params.target, params.prompt];
-					if (shouldWait) args.push("--wait");
-					for (const status of params.until || []) args.push("--until", status);
-					if (params.timeout != null) args.push("--timeout", String(params.timeout));
-					if (shouldWait) {
-						onUpdate?.({
-							content: [{ type: "text", text: `Prompted ${params.target}; waiting for lifecycle settlement...` }],
-							details: { action: "prompt", target: params.target, waiting: true },
-						});
-					}
-					let response: { result: { agent: AgentInfo } } | null;
-					let stalledState: string | undefined;
-					try {
-						response = await execHerdrJson<{ result: { agent: AgentInfo } }>(args, signal);
-					} catch (error) {
-						if (isPromptBlocked(error)) {
-							const herdrMessage = error instanceof Error ? error.message : String(error);
-							throw new Error(
-								`${params.target} 处于 blocked（等待审批或回答），herdr 在发送任何输入前就拒绝了本次 prompt：${herdrMessage}\n` +
-									"先用 herdr_agent get / read 看清阻塞的界面，向用户确认怎么答，再用 herdr_agent prompt 或 herdr_pane send_keys 回应；不要重复下发。",
-							);
-						}
-						if (!isPromptStalled(error)) throw error;
-						stalledState = /status is (\w+)/.exec(error instanceof Error ? error.message : "")?.[1];
-						response = null;
-					}
-					if (response === null) {
-						// herdr 在 submission accepted 后要求 5s 内观测到 working/blocked，观测不到就报
-						// agent_prompt_stalled —— 这是启发式，prompt 已经下发，不能当成“下发失败”。
-						return {
-							content: [
-								{
-									type: "text",
-									text:
-										`Prompt 已下发到 ${params.target}（submission accepted），但 5s 内未观测到进入 working/blocked` +
-										(stalledState ? `（当前状态 ${stalledState}）` : "") +
-										"。\n不要再下发一次；用 herdr_agent read 确认它是否已开始工作。",
-								},
-							],
-							details: {
-								action: "prompt",
-								target: params.target,
-								submitted: true,
-								stalled: true,
-								observedState: stalledState,
-							},
-						};
-					}
-					return {
-						content: [{ type: "text", text: `${shouldWait ? "Prompt settled" : "Prompt submitted"}: ${summarizeAgent(response.result.agent)}` }],
-						details: { action: "prompt", agent: response.result.agent },
-					};
-				}
-				case "wait": {
-					if (!params.target) throw new Error("'target' is required for wait");
-					const args = ["agent", "wait", params.target];
-					for (const status of params.until || []) args.push("--until", status);
-					if (params.timeout != null) args.push("--timeout", String(params.timeout));
-					onUpdate?.({
-						content: [{ type: "text", text: `Waiting for agent ${params.target}...` }],
-						details: { action: "wait", target: params.target, waiting: true },
-					});
-					const response = await execHerdrJson<{ result: { agent: AgentInfo } }>(args, signal);
-					return {
-						content: [{ type: "text", text: `Agent settled: ${summarizeAgent(response.result.agent)}` }],
-						details: { action: "wait", agent: response.result.agent },
-					};
-				}
-				case "read": {
-					if (!params.target) throw new Error("'target' is required for read");
-					const args = ["agent", "read", params.target, "--source", params.source || "recent-unwrapped"];
-					if (params.lines != null) args.push("--lines", String(params.lines));
-					if (params.format) args.push("--format", params.format as OutputFormat);
-					const output = await execHerdrText(args, signal);
-					return {
-						content: [{ type: "text", text: formatOutput(output) }],
-						details: { action: "read", target: params.target, read: true, source: params.source || "recent-unwrapped" },
-					};
-				}
-				case "send_keys": {
-					if (!params.target) throw new Error("'target' is required for send_keys");
-					if (!params.keys?.length) throw new Error("'keys' is required for send_keys");
-					await execHerdrJson(["agent", "send-keys", params.target, ...params.keys], signal);
-					return {
-						content: [{ type: "text", text: `Sent ${params.keys.join(" ")} to ${params.target}` }],
-						details: { action: "send_keys", target: params.target, keys: params.keys },
-					};
-				}
-				case "focus": {
-					if (!params.target) throw new Error("'target' is required for focus");
-					const response = await execHerdrJson<{ result: { agent: AgentInfo } }>(["agent", "focus", params.target], signal);
-					return {
-						content: [{ type: "text", text: `Focused ${agentDisplayName(response.result.agent)}` }],
-						details: { action: "focus", agent: response.result.agent },
-					};
-				}
-				case "rename": {
-					if (!params.target) throw new Error("'target' is required for rename");
-					if (!params.clearName && !params.name) throw new Error("'name' or 'clearName' is required for rename");
-					const args = ["agent", "rename", params.target];
-					args.push(params.clearName ? "--clear" : params.name!);
-					const response = await execHerdrJson<{ result: { agent: AgentInfo } }>(args, signal);
-					return {
-						content: [{ type: "text", text: params.clearName ? `Cleared agent name for ${params.target}` : `Renamed agent to ${params.name}` }],
-						details: { action: "rename", agent: response.result.agent },
-					};
-				}
+		async execute(_toolCallId, params, signal) {
+			// herdr CLI 与 dsh 的 skill 脚本都在这一层校验；校验放在 body 里而不是 schema 的
+			// pattern 上，让八个工具的失败都走同一套信封（同一约束只保留一处真值）。
+			if (!AGENT_NAME_PATTERN.test(params.name ?? "")) {
+				return envelopeResult(
+					precondition("'name' must match ^[a-z][a-z0-9_-]{0,31}$（小写字母开头，可含数字/_/-，最长 32 字符）。"),
+				);
+			}
+			if (params.timeoutMs != null && (params.timeoutMs <= START_TIMEOUT_MIN || params.timeoutMs > START_TIMEOUT_MAX)) {
+				return envelopeResult(
+					precondition(`start timeout must be > ${START_TIMEOUT_MIN}ms and <= ${START_TIMEOUT_MAX}ms（单位毫秒）。`),
+				);
+			}
+			const args = ["agent", "start", params.name, "--kind", params.kind, "--pane", params.pane];
+			if (params.timeoutMs != null) args.push("--timeout", String(params.timeoutMs));
+			if (params.agentArgs?.length) args.push("--", ...params.agentArgs);
+			const started = await jsonCall<{ result: { agent: AgentInfo } }>(args, signal);
+			if (started.ok !== true) return envelopeResult(failureEnvelope(started));
+			return envelopeResult({
+				ok: true,
+				exitCode: 0,
+				output: `Started ${summarizeAgent(started.value.result.agent)}`,
+			});
+		},
+		renderCall(args, theme, context) {
+			return renderVerbCall("herdr_agent_start", args, theme, context);
+		},
+		renderResult(result, options, theme) {
+			return renderVerbResult(result, options, theme);
+		},
+	});
+
+	pi.registerTool({
+		name: "herdr_close",
+		label: "Herdr Close",
+		outputSchema: envelopeOutputSchema,
+		description:
+			"关 pane（会杀掉里面的进程）。默认 dryRun=true 只预览目标、不真关；确认目标无误后再显式传 dryRun=false。工具拒绝关闭自己所在的 pane，也绝不要关不是你创建的 pane。",
+		promptSnippet: "预览或关闭一个 pane（默认只预览）",
+		promptGuidelines: [
+			"herdr_close 默认只预览：先看清要关的是哪个 pane，再显式传 dryRun=false 真关。",
+			"关 pane 会杀掉里面的进程且不可撤销；不要关不是你创建的 pane，除非用户明确要求。",
+			"工具永远拒绝关闭当前进程自己所在的 pane。",
+		],
+		parameters: Type.Object({
+			pane: Type.String({ description: "完整限定 pane id" }),
+			dryRun: Type.Optional(Type.Boolean({ description: "默认 true：只预览。要真关必须显式传 false" })),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const current = await attempt(signal, DEFAULT_LOCAL_TIMEOUT, (s) => getCurrentPane(s));
+			if (current.ok !== true) return envelopeResult(failureEnvelope(current));
+			if (params.pane === current.value.pane_id) {
+				return envelopeResult(
+					precondition(
+						"Refusing to close the pane pi is running in.\n  先跑 herdr_overview 确认自己的 pane；要关的是别的 pane。",
+					),
+				);
+			}
+			// 关 pane 会杀掉进程且不可撤销：默认预览，让目标先落在屏幕上再动手。
+			if (params.dryRun !== false) {
+				const target = await attempt(signal, DEFAULT_LOCAL_TIMEOUT, (s) => getPane(params.pane, s));
+				if (target.ok !== true) return envelopeResult(failureEnvelope(target));
+				return envelopeResult({
+					ok: true,
+					exitCode: 0,
+					output: `dry-run: would close ${summarizePane(target.value)}. 再调一次并传 dryRun=false 才会真的关。`,
+				});
 			}
+			const closed = await jsonCall(["pane", "close", params.pane], signal);
+			if (closed.ok !== true) return envelopeResult(failureEnvelope(closed));
+			return envelopeResult({ ok: true, exitCode: 0, output: `Closed pane ${params.pane}` });
 		},
 		renderCall(args, theme, context) {
-			return renderToolCall("herdr_agent", args, theme, context);
+			return renderVerbCall("herdr_close", args, theme, context);
 		},
 		renderResult(result, options, theme) {
-			return renderToolResult(result, options, theme);
+			return renderVerbResult(result, options, theme);
 		},
 	});
 }