{"_id":"@buckeyestudio/toh-tool-ask-user","name":"@buckeyestudio/toh-tool-ask-user","dist-tags":{"next":"0.1.1-rc.2","latest":"0.1.1-rc.2"},"versions":{"0.1.1-rc.2":{"name":"@buckeyestudio/toh-tool-ask-user","description":"Model-facing ask_user_question tool over the ctx.userQuestions seam","version":"0.1.1-rc.2","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-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"},"license":"MIT","author":{"name":"buckeyestudio"},"peerDependencies":{"@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1","@buckeyestudio/toh-user-questions":"^0.1.1-rc.2","@buckeyestudio/toh-agent":"^0.1.1-rc.2"},"devDependencies":{"@buckeyestudio/toh-agent":"^0.1.1-rc.2","@buckeyestudio/toh-invariants":"^0.1.1-rc.2","@buckeyestudio/toh-llm":"^0.1.1-rc.2","@buckeyestudio/toh-tools":"^0.1.1-rc.2","@buckeyestudio/toh-user-questions":"^0.1.1-rc.2","@buckeyestudio/toh-system-prompt":"^0.1.1-rc.2","@buckeyestudio/cordis":"^4.0.1"},"_id":"@buckeyestudio/toh-tool-ask-user@0.1.1-rc.2","bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","_integrity":"sha512-uIYhbUK63le/GyOR4USBcgw91GPIYp4VWjZ7poLWWlo6y7m1gzUz+F5qbySnWVfrs4GlBOUeqQKKRHR2RWBWKw==","_resolved":"/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-ask-user-0.1.1-rc.2.tgz","_from":"file:/home/runner/work/theopen-harness/theopen-harness/dist/npm/buckeyestudio-toh-tool-ask-user-0.1.1-rc.2.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-uIYhbUK63le/GyOR4USBcgw91GPIYp4VWjZ7poLWWlo6y7m1gzUz+F5qbySnWVfrs4GlBOUeqQKKRHR2RWBWKw==","shasum":"5863d48fd06e7ecb713131b25b42d1e6726de690","tarball":"https://registry.npmjs.org/@buckeyestudio/toh-tool-ask-user/-/toh-tool-ask-user-0.1.1-rc.2.tgz","fileCount":9,"unpackedSize":15280,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCDmqWh8HtlCvHZRYJLQE5N93ju4WQnJYiBHpZp5swDAgIhANEf1NaQsJ6vJd4CuAOr3rzxahvwjzYkr+GRvoaGDitj"}]},"_npmUser":{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"},"directories":{},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toh-tool-ask-user_0.1.1-rc.2_1787489561364_0.7651625124829311"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T12:52:41.236Z","0.1.1-rc.2":"2026-08-23T12:52:41.514Z","modified":"2026-08-23T12:52:41.658Z"},"maintainers":[{"name":"buckeyestudio","email":"dustinwloring1988@gmail.com"}],"description":"Model-facing ask_user_question tool over the ctx.userQuestions seam","homepage":"https://github.com/dustinwloring1988/theopen-harness#readme","repository":{"type":"git","url":"git+https://github.com/dustinwloring1988/theopen-harness.git","directory":"packages/interaction/tool-ask-user"},"author":{"name":"buckeyestudio"},"bugs":{"url":"https://github.com/dustinwloring1988/theopen-harness/issues"},"license":"MIT","readme":"# @buckeyestudio/toh-tool-ask-user\n\n[English](README.md) | 中文\n\n模型侧 `ask_user_question` 工具，基于 `ctx.userQuestions` 实现。当模型需要确认、选择结果或缺失的信息才能继续时，它可以借此向用户提出简明问题。\n\n## 工具\n\n`ask_user_question` 接受以下参数：\n\n- `questions`：必填的非空问题对象数组。\n- `id`：每个问题必填的稳定 id，会原样包含在回答中。\n- `question`：每个问题必填的问题文本。\n- `header`：可选的简短标题。\n- `options`：可选选项，包含 `label` 和 `description`。如需推荐某个选项，请将其置于首位，并在该标签末尾追加 `(Recommended)`。\n- `multi_select`：该问题是否可以返回多个选中的选项。\n\n工具调用 `ctx.userQuestions.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；`custom` 携带自由填写的回答，对于多选题会补充 `selected`，对于单选题则会覆盖它。Native 渲染器会保留紧凑的 JSON 文本形式 `{ \"answers\": [{ \"id\": \"...\", \"selected\": [\"...\"], \"custom\": \"...\" }] }`。\n\n## 职责\n\n此包是用户交互 seam 的Consumer 包。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。\n\n## 模型体验\n\n### 工具 schema\n\n#### 模型看到的内容\n\n模型会看到生成的 [`ask_user_question` schema](../../../docs/tool-catalog.zh.md#buckeyestudiotoh-tool-ask-user)，其中包含问题 id、提示语、标题、选项和多选标志。\n\n#### Token 影响\n\n工具可见时，每个请求都会产生固定的 schema token 开销。\n\n#### KV Cache 影响\n\n只要定义和可见性保持不变，前缀即可稳定复用。插件生命周期变化或作用域限制可能会使从此 schema 起的缓存复用失效。\n\n### 工具调用历史与结果\n\n#### 模型看到的内容\n\n模型提出的完整问题保留在 assistant 工具调用参数中。用户回答后，下一步会看到精确采用 `{\"answers\":[{\"id\":\"<id>\",\"selected\":[\"<label>\"],\"custom\":\"<text>\"}]}` 形式的紧凑 JSON；不使用 `custom` 时会省略该字段，`selected` 可以包含零个、一个或多个标签。调用等待期间的 UI 交互不属于模型上下文。\n\n#### Token 影响\n\n参数和回答 JSON 是依数据而定的保留 token；等待用户时不会产生 token 开销。\n\n#### KV Cache 影响\n\n仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n## 已知限制与暂缓事项\n\n- **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。\n- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝归属于另一个 agent 的存活子级；该子级必须在最终结果中包含尚未解决的问题或决策。持久谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。\n- **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。\n","readmeFilename":"README.zh.md","_rev":"1-0f8bcc5150f5409deb11ac5af26c3326"}