@poncho-ai/harness 0.59.13 → 0.59.14

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.13 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.59.14 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -9,8 +9,8 @@
 CLI Target: es2022
 ESM Build start
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            561.36 KB
-ESM ⚡️ Build success in 214ms
+ESM dist/index.js            564.58 KB
+ESM ⚡️ Build success in 217ms
 DTS Build start
-DTS ⚡️ Build success in 8568ms
+DTS ⚡️ Build success in 8055ms
 DTS dist/index.d.ts 102.50 KB

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @poncho-ai/harness
 
+## 0.59.14
+
+### Patch Changes
+
+- [#172](https://github.com/cesr/poncho-ai/pull/172) [`dc61836`](https://github.com/cesr/poncho-ai/commit/dc61836aa99e3cb6e1339dc6f82ffdab522918ba) Thanks [@cesr](https://github.com/cesr)! - Add the `ask_user` built-in tool: the agent can pause the run to ask the
+  user a structured, multiple-choice question (the in-app analog of Claude
+  Code's AskUserQuestion) instead of asking in plain prose. Each call
+  carries 1–4 questions, each with a short header, a `multiSelect` flag,
+  and pre-made options; a free-text "Other" escape is rendered by the
+  client.
+
+  The tool is forced to client (`device`) dispatch, so the harness pauses
+  the run on a checkpoint carrying the questions and the consumer resumes
+  by injecting the user's selections as the tool result — no server-side
+  execution (the handler is a defensive stub). The default agent prompt
+  now steers the model to reach for `ask_user` whenever it would otherwise
+  stop to ask the user to choose between options.
+
 ## 0.59.13
 
 ### Patch Changes

package/dist/index.js

@@ -710,7 +710,7 @@ Environment: {{runtime.environment}}
 
 - Use tools when needed
 - Explain your reasoning clearly
-- Ask clarifying questions when requirements are ambiguous
+- When requirements are ambiguous or you need the user to choose between options, use the \`ask_user\` tool to ask a structured multiple-choice question instead of writing the question as plain text. Reserve plain-text questions for genuinely open-ended asks that have no sensible pre-made options.
 - Never claim a file/tool change unless the corresponding tool call actually succeeded
 `;
 };
@@ -2445,7 +2445,7 @@ var ponchoDocsTool = defineTool({
 import { randomUUID as randomUUID5 } from "crypto";
 import { readFile as readFile9 } from "fs/promises";
 import { resolve as resolve11 } from "path";
-import { defineTool as defineTool12, getTextContent as getTextContent2, createLogger as createLogger7, formatError as fmtErr, url as urlColor } from "@poncho-ai/sdk";
+import { defineTool as defineTool13, getTextContent as getTextContent2, createLogger as createLogger7, formatError as fmtErr, url as urlColor } from "@poncho-ai/sdk";
 
 // src/upload-store.ts
 import { createHash as createHash2 } from "crypto";
@@ -8591,10 +8591,71 @@ var createSearchTools = () => [
   })
 ];
 
-// src/subagent-tools.ts
+// src/ask-user-tool.ts
 import { defineTool as defineTool11 } from "@poncho-ai/sdk";
+var createAskUserTool = () => defineTool11({
+  name: "ask_user",
+  description: "Ask the user one or more structured multiple-choice questions and wait for their answer. Use this INSTEAD of writing a question as plain text whenever you would otherwise pause to let the user choose between options \u2014 clarifying ambiguous requirements, picking an approach, confirming a direction. The user sees tappable option chips and answers with a tap. Prefer this over a prose question: it is faster for the user and gives you a clean answer. Guidelines: ask 1\u20134 questions at once, each with 2\u20134 concrete options; keep `header` very short (a few words); write each option `label` short and its `description` to one line. The user can always type a custom 'Other' answer, so you do not need to add one. Do NOT call any other tool in the same turn as ask_user, and call it at most once per turn. After the user answers you will receive their selections and may continue.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      questions: {
+        type: "array",
+        description: "1\u20134 questions to ask the user at once.",
+        items: {
+          type: "object",
+          properties: {
+            question: {
+              type: "string",
+              description: "The full question text shown to the user."
+            },
+            header: {
+              type: "string",
+              description: "A very short label for this question (a few words, ~12 chars), shown as a chip."
+            },
+            multiSelect: {
+              type: "boolean",
+              description: "If true, the user may select multiple options. Defaults to false (single choice)."
+            },
+            options: {
+              type: "array",
+              description: "The pre-made options. A free-text 'Other' option is added automatically by the client.",
+              items: {
+                type: "object",
+                properties: {
+                  label: {
+                    type: "string",
+                    description: "Short, selectable label for this option."
+                  },
+                  description: {
+                    type: "string",
+                    description: "A one-line explanation of what this option means."
+                  }
+                },
+                required: ["label"],
+                additionalProperties: false
+              }
+            }
+          },
+          required: ["question", "header", "options"],
+          additionalProperties: false
+        }
+      }
+    },
+    required: ["questions"],
+    additionalProperties: false
+  },
+  handler: async () => {
+    return {
+      error: "ask_user must be answered by the user on the client; it cannot run server-side. This indicates a dispatch misconfiguration."
+    };
+  }
+});
+
+// src/subagent-tools.ts
+import { defineTool as defineTool12 } from "@poncho-ai/sdk";
 var createSubagentTools = (manager) => [
-  defineTool11({
+  defineTool12({
     name: "spawn_subagent",
     description: "Spawn a subagent to work on a task in the background. Returns immediately with a subagent ID. The subagent runs independently and its result will be delivered to you as a message in the conversation when it completes.\n\nGuidelines:\n- Spawn all needed subagents in a SINGLE response (they run concurrently), then end your turn with a brief message to the user.\n- Do NOT spawn more subagents in follow-up steps. Wait for results to be delivered before deciding if more work is needed.\n- Prefer doing work yourself for simple or quick tasks. Spawn subagents for substantial, self-contained work.\n- The subagent has no memory of your conversation -- write thorough, self-contained instructions in the task.",
     inputSchema: {
@@ -8629,7 +8690,7 @@ var createSubagentTools = (manager) => [
       return { subagentId, status: "running" };
     }
   }),
-  defineTool11({
+  defineTool12({
     name: "message_subagent",
     description: "Send a follow-up message to a completed or stopped subagent. The subagent restarts in the background and its result will be delivered to you as a message when it completes. Only works when the subagent is not currently running.",
     inputSchema: {
@@ -8657,7 +8718,7 @@ var createSubagentTools = (manager) => [
       return { subagentId: id, status: "running" };
     }
   }),
-  defineTool11({
+  defineTool12({
     name: "stop_subagent",
     description: "Stop a running subagent. The subagent's conversation is preserved but it will stop processing. Use this to cancel work that is no longer needed.",
     inputSchema: {
@@ -8680,7 +8741,7 @@ var createSubagentTools = (manager) => [
       return { message: `Subagent "${subagentId}" has been stopped.` };
     }
   }),
-  defineTool11({
+  defineTool12({
     name: "list_subagents",
     description: "List all subagents that have been spawned in this conversation. Returns each subagent's ID, original task, current status, and message count. Use this to look up subagent IDs before calling message_subagent or stop_subagent.",
     inputSchema: {
@@ -8700,7 +8761,7 @@ var createSubagentTools = (manager) => [
       return { subagents };
     }
   }),
-  defineTool11({
+  defineTool12({
     name: "read_subagent",
     description: "Fetch the conversation transcript of a subagent you spawned. Use this to inspect a subagent's intermediate reasoning, tool calls, or full output -- instead of asking it to repeat its work via message_subagent.\n\nModes:\n- 'final' (default): just the last assistant message. Cheap.\n- 'assistant': all assistant messages, no tool calls/results.\n- 'full': every message including tool calls and results. Can be large.\n\nUse since_index / max_messages to page through long transcripts. Only works on subagents directly spawned by this conversation.",
     inputSchema: {
@@ -9578,6 +9639,7 @@ var AgentHarness = class _AgentHarness {
   }
   /** Returns the normalized {access, dispatch} mode for the tool. */
   resolveToolMode(toolName) {
+    if (toolName === "ask_user") return { dispatch: "device" };
     return normalizeToolAccess(this.resolveToolAccess(toolName));
   }
   isToolEnabled(name) {
@@ -9619,6 +9681,9 @@ var AgentHarness = class _AgentHarness {
         this.registerIfMissing(tool);
       }
     }
+    if (this.isToolEnabled("ask_user")) {
+      this.registerIfMissing(createAskUserTool());
+    }
     if (this.environment === "development" && this.isToolEnabled("poncho_docs")) {
       this.registerIfMissing(ponchoDocsTool);
     }
@@ -9627,7 +9692,7 @@ var AgentHarness = class _AgentHarness {
     }
   }
   createGetToolResultByIdTool() {
-    return defineTool12({
+    return defineTool13({
       name: "get_tool_result_by_id",
       description: "Retrieve a previously archived full tool result by id for the current conversation. Use this when older tool outputs were truncated in prompt history.",
       inputSchema: {
@@ -14654,7 +14719,7 @@ ${draft.toolTimeline.join("\n")}`);
 };
 
 // src/index.ts
-import { defineTool as defineTool13 } from "@poncho-ai/sdk";
+import { defineTool as defineTool14 } from "@poncho-ai/sdk";
 export {
   AgentHarness,
   AgentOrchestrator,
@@ -14728,7 +14793,7 @@ export {
   createWriteTool,
   decodeFileInputData,
   defaultAgentDefinition,
-  defineTool13 as defineTool,
+  defineTool14 as defineTool,
   deleteOpenAICodexSession,
   deriveUploadKey,
   ensureAgentIdentity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.59.13",
+  "version": "0.59.14",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/ask-user-tool.ts

@@ -0,0 +1,95 @@
+import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+
+// ---------------------------------------------------------------------------
+// ask_user — pause the run to ask the user a structured, multiple-choice
+// question with pre-made options (the in-app analog of Claude Code's
+// AskUserQuestion). The client renders tappable option chips so the user
+// answers with a tap instead of typing prose.
+//
+// This tool is dispatched to the client ("device" dispatch, forced in
+// AgentHarness.resolveToolMode): the harness pauses the run, emits a
+// checkpoint carrying the questions payload, and the consumer (PonchOS)
+// resumes the run by POSTing the user's selections back as this tool's
+// result. The handler below is a defensive stub — device dispatch
+// intercepts the call before any server-side execution, so it must never
+// actually run.
+// ---------------------------------------------------------------------------
+
+export const createAskUserTool = (): ToolDefinition =>
+  defineTool({
+    name: "ask_user",
+    description:
+      "Ask the user one or more structured multiple-choice questions and wait for their answer. " +
+      "Use this INSTEAD of writing a question as plain text whenever you would otherwise pause to " +
+      "let the user choose between options — clarifying ambiguous requirements, picking an approach, " +
+      "confirming a direction. The user sees tappable option chips and answers with a tap. " +
+      "Prefer this over a prose question: it is faster for the user and gives you a clean answer. " +
+      "Guidelines: ask 1–4 questions at once, each with 2–4 concrete options; keep `header` very short " +
+      "(a few words); write each option `label` short and its `description` to one line. The user can " +
+      "always type a custom 'Other' answer, so you do not need to add one. Do NOT call any other tool " +
+      "in the same turn as ask_user, and call it at most once per turn. After the user answers you will " +
+      "receive their selections and may continue.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        questions: {
+          type: "array",
+          description: "1–4 questions to ask the user at once.",
+          items: {
+            type: "object",
+            properties: {
+              question: {
+                type: "string",
+                description: "The full question text shown to the user.",
+              },
+              header: {
+                type: "string",
+                description:
+                  "A very short label for this question (a few words, ~12 chars), shown as a chip.",
+              },
+              multiSelect: {
+                type: "boolean",
+                description:
+                  "If true, the user may select multiple options. Defaults to false (single choice).",
+              },
+              options: {
+                type: "array",
+                description:
+                  "The pre-made options. A free-text 'Other' option is added automatically by the client.",
+                items: {
+                  type: "object",
+                  properties: {
+                    label: {
+                      type: "string",
+                      description: "Short, selectable label for this option.",
+                    },
+                    description: {
+                      type: "string",
+                      description: "A one-line explanation of what this option means.",
+                    },
+                  },
+                  required: ["label"],
+                  additionalProperties: false,
+                },
+              },
+            },
+            required: ["question", "header", "options"],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ["questions"],
+      additionalProperties: false,
+    },
+    handler: async () => {
+      // Unreachable in normal operation: ask_user is forced to client/device
+      // dispatch, so the harness checkpoints before this handler is invoked.
+      // If it ever runs, the tool was misconfigured (dispatch not forced) —
+      // surface an error rather than silently resolving with no user input.
+      return {
+        error:
+          "ask_user must be answered by the user on the client; it cannot run server-side. " +
+          "This indicates a dispatch misconfiguration.",
+      };
+    },
+  });

package/src/default-agent.ts

@@ -100,7 +100,7 @@ Environment: {{runtime.environment}}
 
 - Use tools when needed
 - Explain your reasoning clearly
-- Ask clarifying questions when requirements are ambiguous
+- When requirements are ambiguous or you need the user to choose between options, use the \`ask_user\` tool to ask a structured multiple-choice question instead of writing the question as plain text. Reserve plain-text questions for genuinely open-ended asks that have no sensible pre-made options.
 - Never claim a file/tool change unless the corresponding tool call actually succeeded
 `;
 };

package/src/harness.ts

@@ -65,6 +65,7 @@ import { jsonSchemaToZod } from "./schema-converter.js";
 import type { SkillMetadata } from "./skill-context.js";
 import { createSkillTools, normalizeScriptPolicyPath } from "./skill-tools.js";
 import { createSearchTools } from "./search-tools.js";
+import { createAskUserTool } from "./ask-user-tool.js";
 import { createSubagentTools } from "./subagent-tools.js";
 import type { SubagentManager } from "./subagent-manager.js";
 import { trace, context as otelContext, createContextKey, type Context as OtelContextType, SpanStatusCode, SpanKind, diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
@@ -965,6 +966,11 @@ export class AgentHarness {
 
   /** Returns the normalized {access, dispatch} mode for the tool. */
   private resolveToolMode(toolName: string): { access?: "approval"; dispatch?: "device" } {
+    // ask_user is always answered by the user on the client. Force device
+    // dispatch unconditionally so it pauses the run and checkpoints rather
+    // than running its (defensive, error-returning) server-side handler —
+    // even if no `poncho.config.js` entry exists for it.
+    if (toolName === "ask_user") return { dispatch: "device" };
     return normalizeToolAccess(this.resolveToolAccess(toolName));
   }
 
@@ -1014,6 +1020,9 @@ export class AgentHarness {
         this.registerIfMissing(tool);
       }
     }
+    if (this.isToolEnabled("ask_user")) {
+      this.registerIfMissing(createAskUserTool());
+    }
     if (this.environment === "development" && this.isToolEnabled("poncho_docs")) {
       this.registerIfMissing(ponchoDocsTool);
     }