@zhushanwen/pi-ask-user 7.3.7 → 7.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.3.7",
+  "version": "7.3.8",
   "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview and an inline free-text editor.",
   "type": "module",
   "main": "index.ts",

package/src/__tests__/index.test.ts

@@ -42,7 +42,9 @@ interface RegisteredTool {
 interface MockPi {
 	tool?: RegisteredTool;
 	registerTool(tool: RegisteredTool): void;
-	getAllTools(): { name: string }[];
+	getAllTools(): { name: string; exposure?: string }[];
+	/** 当前激活集（快照式禁用的基底，dmg-r1-2）；缺省 = 全部 direct 工具激活 */
+	getActiveTools(): string[];
 	activeTools?: string[] | null;
 	setActiveTools(names: string[]): void;
 	// session_start handler：factory 注册 ask_user channel handler 时调用（透传功能）。
@@ -57,7 +59,13 @@ const getTool = (overrides: Partial<MockPi> = {}): RegisteredTool => {
 			this.tool = tool;
 		},
 		getAllTools() {
-			return [{ name: "ask_user" }, { name: "other_tool" }];
+			return [
+				{ name: "ask_user", exposure: "direct" },
+				{ name: "other_tool", exposure: "direct" },
+			];
+		},
+		getActiveTools() {
+			return ["ask_user", "other_tool"];
 		},
 		setActiveTools(names) {
 			this.activeTools = names;
@@ -226,7 +234,17 @@ describe("execute — headless (FR-8 / AC-7)", () => {
 	it("I-6: headless disables ask_user tool via setActiveTools (收尾先于 throw)", async () => {
 		let captured: string[] | null = null;
 		const tool2 = getTool({
-			getAllTools: () => [{ name: "ask_user" }, { name: "other" }],
+			// 快照式禁用基底（dmg-r1-2）：getActiveTools = 当前激活集；getAllTools 注册全集
+			// 含未激活的 plan(deferred) 与 tool_search(model-only + defaultActive:false，pi
+			// tool-search/index.js 实装)——禁用动作不得把它们点名激活（setActiveTools
+			// 点名即声明给模型）
+			getActiveTools: () => ["ask_user", "other"],
+			getAllTools: () => [
+				{ name: "ask_user", exposure: "direct" },
+				{ name: "other", exposure: "direct" },
+				{ name: "plan", exposure: "deferred" },
+				{ name: "tool_search", exposure: "model-only" },
+			],
 			setActiveTools: (names: string[]) => {
 				captured = names;
 			},
@@ -236,6 +254,10 @@ describe("execute — headless (FR-8 / AC-7)", () => {
 		).rejects.toThrow();
 		expect(captured).not.toContain("ask_user");
 		expect(captured).toContain("other");
+		// D4 回归锚：未激活工具不随禁用动作常驻——含 model-only 档但 defaultActive:false
+		// 的 tool_search（按档位过滤重建会点名激活它，快照式基底天然不含）
+		expect(captured).not.toContain("plan");
+		expect(captured).not.toContain("tool_search");
 	});
 });
 
@@ -818,7 +840,11 @@ describe("execute — RPC mode (uiFormInteract via select channel)", () => {
 	it("R-10: select 回显 payload（echo，旧 taiji 宿主）→ channel-error throw 带升级指引 + 工具禁用", async () => {
 		let capturedActive: string[] | null = null;
 		const tool = getTool({
-			getAllTools: () => [{ name: "ask_user" }, { name: "other" }],
+			getActiveTools: () => ["ask_user", "other"],
+			getAllTools: () => [
+				{ name: "ask_user", exposure: "direct" },
+				{ name: "other", exposure: "direct" },
+			],
 			setActiveTools: (names: string[]) => {
 				capturedActive = names;
 			},

package/src/__tests__/prompt-quality.test.ts

@@ -12,6 +12,20 @@
 //
 // 本测试用源码断言（读 .ts 文件文本）锁定这些约束，防止后续重构把正例/反例/调用信号
 // 删掉或弱化。读源码而非 import，避免 mock 链（index.ts 依赖 pi-tui/ExtensionAPI 等）。
+//
+// 【锚词保留清单 — ask_user】（tool-declaration-slimming D2：压缩后的契约 = 逐锚词
+// grep，替代原逐字断言。U-A1 终态：promptGuidelines 层已删——原 6 条与 description/
+// InputSchema 字段说明逐条重复；调用信号 + 唯一正例 + 结构反例单点在 description）：
+//  Q1  '"options":[{"label"' —— 单问题正例的对象数组形态（弱模型最高频误用面）
+//  Q2  '"header"' ≥2 —— 批量正例展示条件必填字段
+//  Q3  "(Recommended)" —— 推荐项前缀调用信号
+//  Q4  结构反例 ≥2：string array / Flatten / Other（描述里 Don't 段承载）
+//  Q5  "Use ONLY when" + "Do NOT use" —— 调用门槛与边界段
+//  Q6  validate.ts 三个 Correct 正例锚（runtime 友好纠错，未改动）
+//  Q7  示例必须与契约一致：options 元素必须 {label, description} 对象形态
+//  Q8  "mutually exclusive" —— 一问题一决策、选项互斥的提问纪律（单句并入推荐项
+//      段落；U-A1 压缩曾删原纪律句，选项级互斥语义由 InputSchema options 字段说明
+//      承载，问题级「one question = one decision」唯一承载点 = description 此句）
 
 import { readFileSync } from "node:fs";
 import { dirname,join } from "node:path";
@@ -75,6 +89,13 @@ describe("ask_user description — 调用信号保留（不要破坏亮点）",
 	it("保留 'Do NOT use' 边界段", () => {
 		expect(DESCRIPTION).toContain("Do NOT use");
 	});
+
+	it("保留 'mutually exclusive' 提问纪律（Q8：一问题一决策、选项互斥）", () => {
+		// 问题级纪律没有 runtime 校验可拦（validate 只查结构），弱模型把多个决策
+		// 塞进一个 question、或选项互斥性存疑时只有这条声明面约束。
+		expect(DESCRIPTION).toContain("mutually exclusive");
+		expect(DESCRIPTION).toContain("one decision");
+	});
 });
 
 describe("validate.ts — runtime 友好纠错（A. 带正例）", () => {

package/src/index.ts

@@ -36,14 +36,18 @@ import { validateInput } from "./validate";
  */
 type ExecuteResult = AgentToolResult<AskUserDetails>;
 
-/** 禁用 ask_user 工具（headless / RPC 通道不可用时调用，防 LLM 反复重试）。 */
+/**
+ * 禁用 ask_user 工具（headless / RPC 通道不可用时调用，防 LLM 反复重试）。
+ *
+ * 快照式（D4 tool-declaration-slimming 修订）：基底 = 当前激活集（getActiveTools），
+ * 排除 ask_user 的动作叠加其上——不点任何原本未激活的工具。pi 语义
+ * （setActiveTools 点名即声明给模型，agent-session _applyToolLoadout 只滤 hidden）：
+ * 若按 getAllTools() 全量点名，defer 名单与未 opt-in 的 tool_search（实装
+ * model-only 档 + defaultActive:false 注册）会被点名激活，击穿「未开启 tool_search
+ * 时这些工具对模型不可见」的前提。
+ */
 function disableAskUser(pi: ExtensionAPI): void {
-	pi.setActiveTools(
-		pi
-			.getAllTools()
-			.map((t: { name: string }) => t.name)
-			.filter((n: string) => n !== "ask_user"),
-	);
+	pi.setActiveTools(pi.getActiveTools().filter((n: string) => n !== "ask_user"));
 }
 
 /** 构造 cancelled 结果（用户取消 / abort 共用；错误路径已改为 throw，不走此函数）。 */
@@ -229,32 +233,25 @@ export default function (pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "ask_user",
 		label: "Ask User",
-		description: `Ask the user to resolve ambiguity you cannot resolve yourself. Use ONLY when ALL hold: (1) the request has ≥2 reasonable approaches, (2) you have already gathered context (read/grep) and the answer is still genuinely ambiguous, and (3) picking wrong means redoing real work. One question = one decision with mutually exclusive options.
-
-Do NOT use this tool to outsource judgment you should make — if you can form a defensible recommendation from the codebase, proceed and state your choice. Do NOT use for trivia answerable by reading code/docs, or for simple confirmations ("I'll delete X") where plain text suffices. You cannot use this tool to collect free-form requirements, long-form feedback, or multi-paragraph input — it returns short selections only.
+		// tool-declaration-slimming D1 终态：调用信号 + 一个正例 + 结构反例在 description
+		// 一处；参数功能语义在 InputSchema 字段说明（types.ts）；promptGuidelines 层删除
+		// （原 6 条与 description/schema 逐条重复）。锚词保留清单见 __tests__/prompt-quality.test.ts 头注。
+		description: `Ask the user to resolve ambiguity you cannot resolve. Use ONLY when ALL hold: (1) ≥2 reasonable approaches exist, (2) you already gathered context (read/grep) and it is still genuinely ambiguous, (3) picking wrong means redoing real work.
 
-If you recommend an option, prefix its label with "(Recommended)" and list it first. For structured multi-option decisions, prefer this tool over plain-text questions; for everything else, reply in plain text.
+Do NOT use this tool to outsource judgment you should make — if you can form a defensible recommendation from the codebase, proceed and state it. Not for trivia answerable by reading code/docs, simple confirmations (plain text suffices), or free-form input — it returns short selections only.
 
-Examples:
-{"questions":[{"question":"Which DB?","context":"Need ACID + JSON columns.","options":[{"label":"(Recommended) Postgres","description":"Mature, strong consistency."},{"label":"SQLite","description":"Zero-ops, embedded."}]}]}
+If you recommend an option, prefix its label with "(Recommended)" and list it first. One question = one decision with mutually exclusive options.
 
-{"questions":[{"header":"DB","question":"Which database?","options":[{"label":"Postgres","description":"..."},{"label":"SQLite","description":"..."}]},{"header":"Region","question":"Which region?","options":[{"label":"us-east-1","description":"..."},{"label":"eu-west-1","description":"..."}]}]}
+Example:
+{"questions":[{"header":"DB","question":"Which database?","context":"Need ACID + JSON columns.","options":[{"label":"(Recommended) Postgres","description":"Mature, strong consistency."},{"label":"SQLite","description":"Zero-ops, embedded."}]},{"header":"Region","question":"Which region?","options":[{"label":"us-east-1","description":"..."},{"label":"eu-west-1","description":"..."}]}]}
 
 Don't:
 - Passing options as a string array ("options":["A","B"]) — each option must be {"label","description"}.
-- Forgetting header in multi-question mode (questions.length > 1).
+- Forgetting header when questions.length > 1.
 - Flattening question/header/options to the top level — wrap them in questions:[...].
 - Including an "Other" option — it is added automatically.`,
 		promptSnippet:
 			"Ask the user structured clarifying questions with options — only when you cannot resolve the ambiguity yourself",
-		promptGuidelines: [
-			"Use ask_user only when the request has ≥2 reasonable approaches you cannot resolve from context. Models over-ask because asking feels safer than deciding — resist this: if context makes the answer clear, proceed without asking.",
-			"Gather context first (read/grep) and pass a short summary via the context field — don't ask blind. If the answer becomes clear after gathering context, proceed and state your choice.",
-			"Ask focused questions; each question = one decision with mutually exclusive options. Batch related decisions into one call (1-4 questions).",
-			"Do NOT use ask_user for trivia answerable by reading code/docs, or to confirm simple actions ('I'll delete X') — plain text suffices there.",
-			"Do NOT outsource judgment you can make yourself: if you can form a defensible recommendation from the codebase, proceed and state it instead of asking.",
-			"Do NOT include an 'Other' option yourself — it is always available automatically.",
-		],
 		parameters: InputSchema,
 
 		async execute(