@hydraharness/harness-tool-ask-user 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @hydraharness/harness-tool-ask-user
+
+Model-facing `ask_user_question` tool over `ctx.userQuestions`. It lets the model ask the human a concise question for a user-owned choice or missing information before continuing, including when approval prompts are disabled. Execution permission follows the current sandbox and approval policy through the acting tool's approval flow; a question answer grants no permission and cannot override a denial. When the request clearly implies an available tool or execution path, the model should choose it itself instead of asking the user to choose between tools or implementation options.
+
+## Tool
+
+`ask_user_question` accepts:
+
+- `questions` — required non-empty array of question objects.
+- `id` — required stable id on each question, echoed in the answer.
+- `question` — required question text for each question.
+- `header` — optional short heading.
+- `options` — optional choices with `label` and `description`. If recommending a choice, put it first and append `(Recommended)` to that label.
+- `multi_select` — whether that question may return more than one selected option.
+
+The tool calls `ctx.userQuestions.ask()` and returns canonical `{ answers: [{ id, selected, custom? }] }`. `selected` contains option labels; `custom` carries a free-form answer, supplementing `selected` for a multi-select question and overriding it for a single-select question. The Native renderer preserves the compact JSON text shape `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`.
+
+## Role
+
+This is the Consumer package for the user-questions seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop.
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#hydraharness-tool-ask-user), including question ids, prompts, headings, options, and multi-select flags. It reserves the tool for a concrete task blocked by a user-owned choice or a fact normal inspection cannot establish; execution permission requests, greetings, casual chat, vague requests, and generic action/tool menus are excluded.
+
+#### Token effect
+
+Fixed schema cost on every request where the tool is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the definition and visibility are unchanged. Plugin lifecycle or scoped restrictions may invalidate reuse from this schema.
+
+### Tool-call history and result
+
+#### What the model sees
+
+The model's full questions remain in the assistant tool-call arguments. After the human answers, the next step sees compact JSON in the exact shape `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}`; `custom` is omitted when unused and `selected` can contain zero, one, or several labels. UI interaction while the call is pending is not model context.
+
+#### Token effect
+
+Arguments and answer JSON are data-dependent retained tokens; there is no token cost while waiting for the human.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **A pending question blocks the tool call until the human answers** — the tool declares no `timeout-policy` budget; cancellation rides the turn's `exec.signal` only.
+- **Runtime-owned subagents cannot ask the user** — `ask_user_question` rejects a live child owned by another agent with `DELEGATED_CALLER`; the child must include the unresolved question or decision in its final result. Durable lineage does not decide this boundary, so a lineage-bearing session resumed as a runtime root may ask normally.
+- **Native answers render as JSON text** — the canonical value remains structured, but the model-facing result uses compact JSON rather than a richer content-block vocabulary.

package/lib/index.js

@@ -0,0 +1,171 @@
+import { defineTool } from "@hydraharness/harness-tools";
+import "@hydraharness/harness-user-questions";
+//#region lib/types/index.js
+/**
+* Model-facing Consumer of the `ctx.userQuestions` capability seam.
+* The tool pauses until a UI provider returns a human answer, then feeds that
+* answer back into the agent loop as an ordinary tool result.
+*
+* @module @hydraharness/harness-tool-ask-user
+*/
+const name = "tool-ask-user";
+const inject = ["tools", "userQuestions"];
+const description = "Ask the user a concise question only when a genuine user-owned choice or a material fact unavailable through normal inspection blocks a concrete task. Do not use this to request permission for an action. Follow the current sandbox and approval policy and the acting tool's approval flow; a question answer does not grant permission or override a denial. Necessary clarification questions remain available when approval prompts are disabled. Do not use this for greetings, acknowledgements, casual chat, vague requests, or generic action, task, or tool menus. When the request clearly implies an available tool or execution path, inspect the context, choose it yourself, and proceed; do not ask the user to choose between tools or implementation options. Send one or more questions, each with a stable id that will be echoed in the answer.";
+const GENERIC_IMPROVEMENT_LABELS = new Set([
+	"performance",
+	"features",
+	"reliability",
+	"safety",
+	"security",
+	"latency",
+	"quality",
+	"ux",
+	"user experience",
+	"explainability",
+	"scalability",
+	"hiệu suất",
+	"tính năng",
+	"độ tin cậy",
+	"an toàn",
+	"bảo mật",
+	"độ trễ",
+	"chất lượng",
+	"trải nghiệm người dùng",
+	"khả năng giải thích",
+	"khả năng mở rộng"
+]);
+function latestDirectUserText(agent) {
+	const events = agent?.session.events;
+	if (events === void 0) return;
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event?.type !== "user/message" || event.data.source.kind !== "user") continue;
+		return event.data.content.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n");
+	}
+}
+function isGenericImprovementMenu(value) {
+	if (value === null || typeof value !== "object") return false;
+	const questions = value.questions;
+	if (!Array.isArray(questions)) return false;
+	return questions.some((question) => {
+		if (question === null || typeof question !== "object") return false;
+		const questionText = question.question;
+		const options = question.options;
+		const labels = Array.isArray(options) ? options.flatMap((option) => {
+			if (option === null || typeof option !== "object") return [];
+			const label = option.label;
+			return typeof label === "string" ? [label.trim().toLowerCase()] : [];
+		}) : [];
+		const menuText = [typeof questionText === "string" ? questionText : "", ...labels].join("\n").toLowerCase();
+		return [...GENERIC_IMPROVEMENT_LABELS].filter((label) => menuText.includes(label)).length >= 3;
+	});
+}
+function genericImprovementMenuReason(agent, args) {
+	const userText = latestDirectUserText(agent);
+	if (userText === void 0 || !/(?:\bimprov(?:e|ing|ement)\b|\benhanc(?:e|ing|ement)\b|\boptimi[sz](?:e|ing|ation)\b|cải thiện|nâng cấp|tối ưu)/iu.test(userText) || !isGenericImprovementMenu(args)) return;
+	return "ask_user_question cannot offer a generic improvement-category menu. Inspect the available context and take the smallest safe useful step; ask only for a material fact normal inspection cannot establish or a genuinely user-owned choice.";
+}
+function apply(ctx) {
+	ctx.tools.guard((exec) => exec.name === "ask_user_question" ? genericImprovementMenuReason(exec.agent, exec.arguments) : void 0);
+	ctx.tools.register(defineTool({
+		name: "ask_user_question",
+		description,
+		parameters: { questions: {
+			type: "array",
+			required: true,
+			description: "Questions to ask the user before continuing.",
+			items: {
+				type: "object",
+				additionalProperties: true,
+				properties: {
+					id: {
+						type: "string",
+						required: true,
+						description: "Stable id for this question; echoed in the answer."
+					},
+					question: {
+						type: "string",
+						required: true,
+						description: "The specific question to ask the user."
+					},
+					header: {
+						type: "string",
+						description: "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."
+					},
+					options: {
+						type: "array",
+						description: "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" to that label.",
+						items: {
+							type: "object",
+							additionalProperties: true,
+							properties: {
+								label: {
+									type: "string",
+									required: true,
+									description: "Short user-facing option label."
+								},
+								description: {
+									type: "string",
+									description: "One sentence explaining the tradeoff or impact."
+								}
+							}
+						}
+					},
+					multi_select: {
+						type: "boolean",
+						description: "Whether the user may select more than one option. Defaults to false."
+					}
+				}
+			}
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { answers: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							id: {
+								type: "string",
+								required: true
+							},
+							selected: {
+								type: "array",
+								required: true,
+								items: { type: "string" }
+							},
+							custom: { type: "string" }
+						}
+					}
+				} }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value)
+			}]
+		},
+		async execute(args, exec) {
+			return { answers: (await ctx.userQuestions.ask({
+				questions: args.questions.map((question) => ({
+					id: question.id,
+					question: question.question,
+					...question.header !== void 0 ? { header: question.header } : {},
+					...question.options !== void 0 ? { options: question.options } : {},
+					...question.multi_select !== void 0 ? { multiSelect: question.multi_select } : {}
+				})),
+				...exec.agent !== void 0 ? { agent: exec.agent } : {},
+				signal: exec.signal
+			})).answers.map((answer) => ({
+				id: answer.id,
+				selected: [...answer.selected],
+				...answer.custom !== void 0 ? { custom: answer.custom } : {}
+			})) };
+		}
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-tool-ask-user`.
+* @module @hydraharness/harness-tool-ask-user/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-tool-ask-user";
+/** Cordis companion plugin name. */
+const name = "tool-ask-user-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+* relations are owned by the capability seam it calls.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Model-facing Consumer of the `ctx.userQuestions` capability seam.
+ * The tool pauses until a UI provider returns a human answer, then feeds that
+ * answer back into the agent loop as an ordinary tool result.
+ *
+ * @module @hydraharness/harness-tool-ask-user
+ */
+import type { Context } from '@hydraharness/cordis';
+import '@hydraharness/harness-user-questions';
+export declare const name = "tool-ask-user";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-tool-ask-user`.
+ * @module @hydraharness/harness-tool-ask-user/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-ask-user-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@hydraharness/harness-tool-ask-user",
+  "description": "Model-facing ask_user_question tool over the ctx.userQuestions seam",
+  "hydra": {
+    "plugin": {
+      "application": "Let the agent ask structured questions and wait for the user's answers."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/interaction/tool-ask-user"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-user-questions": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/harness-user-questions": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}