@poncho-ai/harness 0.59.13 → 0.59.15

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.15 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            570.16 KB
+ESM ⚡️ Build success in 242ms
 DTS Build start
-DTS ⚡️ Build success in 8568ms
-DTS dist/index.d.ts 102.50 KB
+DTS ⚡️ Build success in 6639ms
+DTS dist/index.d.ts 103.12 KB

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @poncho-ai/harness
 
+## 0.59.15
+
+### Patch Changes
+
+- [`c5f6d7f`](https://github.com/cesr/poncho-ai/commit/c5f6d7f999bc3d4699295c376b23fc3894302e3a) Thanks [@cesr](https://github.com/cesr)! - Guard a single oversized FRESH tool result from overflowing the context
+  window. `truncateHistoricalToolResults` only shrinks results from prior runs
+  (it deliberately preserves the latest run's results so the model can read what
+  it just fetched), so a tool that returns a payload larger than the window in
+  one shot — e.g. an MCP email-fetch returning 1.6M–3.3M tokens of full bodies —
+  was never truncated and failed the very next step with "prompt is too long".
+
+  The result is now guarded at the moment it's produced, before the
+  `tool:completed` event is emitted (so the WS stream never carries the megabytes
+  either) and before it reaches the model:
+  - **Spill mode** (opt-in via the `__toolResultSpill` run parameter
+    `{ enabled, dir?, thresholdChars?, keepLast? }`): the full payload is written
+    to a VFS file (JSONL for arrays, pretty JSON otherwise) and the model gets a
+    small handle + preview pointing at it, to read back in bounded chunks with
+    bash/jq. Durable and lossless; the spill dir is pruned to `keepLast` files.
+  - **Inline-truncate mode** (default when spill isn't enabled, and the fallback
+    if a spill write fails): the payload is replaced with a preview + "re-run
+    narrower" notice.
+
+  Both modes apply to every tool uniformly (MCP, bash, run_code, subagent
+  results) and only trigger above `thresholdChars` (default 500k ≈ 125k tokens),
+  so normal-sized results are untouched. Inline media (images/PDFs) is separated
+  out first and unaffected.
+
+## 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.d.ts

@@ -1494,6 +1494,17 @@ declare class AgentHarness {
     get frontmatter(): AgentFrontmatter | undefined;
     getToolResultArchive(conversationId: string): Record<string, ArchivedToolResult>;
     private seedToolResultArchive;
+    /**
+     * Guard a single FRESH tool result against overflowing the context window.
+     * `serialized` is the JSON-serialized (media-stripped) output. Returns a
+     * replacement value to put in front of the model (a handle or a truncated
+     * preview) when the result is oversized, or `null` to leave it untouched.
+     * Spilling writes the full payload to a VFS file; on any write failure it
+     * falls back to inline truncation, so this never throws into the run loop.
+     */
+    private guardOversizedToolResult;
+    /** Best-effort: keep only the newest `keepLast` files in the spill dir. */
+    private pruneSpillDir;
     private truncateHistoricalToolResults;
     private shouldPreserveSkillToolResult;
     getTodos(conversationId: string): Promise<TodoItem[]>;

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";
@@ -5649,6 +5649,61 @@ var BashEnvironmentManager = class {
   }
 };
 
+// src/tool-result-guard.ts
+var SPILL_POLICY_PARAM = "__toolResultSpill";
+var DEFAULT_OVERSIZED_TOOL_RESULT_CHARS = 5e5;
+var SPILLED_PREVIEW_CHARS = 6e3;
+var INLINE_TRUNCATE_PREVIEW_CHARS = 6e4;
+var DEFAULT_SPILL_DIR = "/tmp/tool-results";
+var DEFAULT_SPILL_KEEP_LAST = 20;
+var readSpillPolicy = (parameters) => {
+  const raw = parameters?.[SPILL_POLICY_PARAM];
+  const obj = typeof raw === "object" && raw !== null ? raw : {};
+  const thresholdChars = typeof obj.thresholdChars === "number" && obj.thresholdChars > 0 ? obj.thresholdChars : DEFAULT_OVERSIZED_TOOL_RESULT_CHARS;
+  const dir = typeof obj.dir === "string" && obj.dir.startsWith("/") ? obj.dir : DEFAULT_SPILL_DIR;
+  const keepLast = typeof obj.keepLast === "number" && obj.keepLast > 0 ? Math.floor(obj.keepLast) : DEFAULT_SPILL_KEEP_LAST;
+  return { enabled: obj.enabled === true, dir, thresholdChars, keepLast };
+};
+var isOversizedToolResult = (serialized, policy) => serialized.length > policy.thresholdChars;
+var formatSpillPayload = (output) => {
+  if (Array.isArray(output)) {
+    return {
+      content: output.map((row) => JSON.stringify(row)).join("\n"),
+      format: "jsonl",
+      records: output.length
+    };
+  }
+  return { content: JSON.stringify(output ?? null, null, 2), format: "json" };
+};
+var buildSpillHandle = (opts) => {
+  const { toolName, path, format, serialized, records } = opts;
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const isArray = format === "jsonl";
+  return {
+    __toolResultSpilled: true,
+    tool: toolName,
+    path,
+    format,
+    ...records !== void 0 ? { records } : {},
+    totalChars: serialized.length,
+    approxTokens,
+    preview: serialized.slice(0, SPILLED_PREVIEW_CHARS),
+    note: `This result was too large to return inline (~${approxTokens.toLocaleString()} tokens) and was saved to ${path}. Inspect it with bash \u2014 e.g. \`wc -l ${path}\`, \`head -c 4000 ${path}\`, ` + (isArray ? `\`sed -n '1,5p' ${path}\`, \`grep -i <term> ${path}\`, or \`jq\` per line` : `\`grep -i <term> ${path}\``) + `. Do NOT cat or read_file the whole file (it re-overflows). Or re-run the tool with a narrower request (fewer items / a filter / metadata only).`
+  };
+};
+var buildInlineTruncation = (toolName, serialized) => {
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const omittedChars = Math.max(0, serialized.length - INLINE_TRUNCATE_PREVIEW_CHARS);
+  return {
+    __toolResultTruncated: true,
+    tool: toolName,
+    approxTokens,
+    omittedChars,
+    preview: serialized.slice(0, INLINE_TRUNCATE_PREVIEW_CHARS),
+    note: `This result was too large (~${approxTokens.toLocaleString()} tokens) and was truncated to fit the context window \u2014 only the first ${INLINE_TRUNCATE_PREVIEW_CHARS.toLocaleString()} characters are shown. Re-run with a narrower request (fewer items / a filter / metadata only). Do NOT retry the same call unchanged \u2014 it will overflow again.`
+  };
+};
+
 // src/vfs/bash-tool.ts
 import { defineTool as defineTool2 } from "@poncho-ai/sdk";
 var createBashTool = (bashManager) => defineTool2({
@@ -8591,10 +8646,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 +8745,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 +8773,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 +8796,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 +8816,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 +9694,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 +9736,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 +9747,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: {
@@ -9760,6 +9880,59 @@ var AgentHarness = class _AgentHarness {
     this.archivedToolResultsByConversation.set(conversationId, merged);
     return merged;
   }
+  /**
+   * Guard a single FRESH tool result against overflowing the context window.
+   * `serialized` is the JSON-serialized (media-stripped) output. Returns a
+   * replacement value to put in front of the model (a handle or a truncated
+   * preview) when the result is oversized, or `null` to leave it untouched.
+   * Spilling writes the full payload to a VFS file; on any write failure it
+   * falls back to inline truncation, so this never throws into the run loop.
+   */
+  async guardOversizedToolResult(opts) {
+    const { tenantId, toolName, toolCallId, output, serialized, policy } = opts;
+    if (!isOversizedToolResult(serialized, policy)) return null;
+    if (policy.enabled && this.bashManager) {
+      try {
+        const vfs = this.createVfsAccess(tenantId);
+        const { content, format, records } = formatSpillPayload(output);
+        const safeTool = toolName.replace(/[^A-Za-z0-9_-]/g, "_");
+        const path = `${policy.dir}/${safeTool}_${toolCallId}.${format}`;
+        await vfs.mkdir(policy.dir, { recursive: true });
+        await vfs.writeText(path, content);
+        await this.pruneSpillDir(vfs, policy.dir, policy.keepLast);
+        return buildSpillHandle({ toolName, path, format, serialized, records });
+      } catch {
+      }
+    }
+    return buildInlineTruncation(toolName, serialized);
+  }
+  /** Best-effort: keep only the newest `keepLast` files in the spill dir. */
+  async pruneSpillDir(vfs, dir, keepLast) {
+    try {
+      const entries = await vfs.readdir(dir);
+      const names = (Array.isArray(entries) ? entries : []).map((e) => typeof e === "string" ? e : e.name).filter((n) => typeof n === "string");
+      if (names.length <= keepLast) return;
+      const stated = await Promise.all(
+        names.map(async (name) => {
+          try {
+            const s = await vfs.stat(`${dir}/${name}`);
+            return { name, mtime: s.updatedAt ?? 0 };
+          } catch {
+            return { name, mtime: 0 };
+          }
+        })
+      );
+      stated.sort((a, b) => a.mtime - b.mtime);
+      const doomed = stated.slice(0, stated.length - keepLast);
+      for (const d of doomed) {
+        try {
+          await vfs.rm(`${dir}/${d.name}`);
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
   truncateHistoricalToolResults(messages, conversationId) {
     let latestRunId;
     let latestToolMessageIndex = -1;
@@ -10611,6 +10784,7 @@ var AgentHarness = class _AgentHarness {
     const messages = [...input.messages ?? []];
     const conversationId = input.conversationId ?? "__default__";
     this.seedToolResultArchive(conversationId, input.parameters);
+    const spillPolicy = readSpillPolicy(input.parameters);
     const truncationSummary = this.truncateHistoricalToolResults(messages, conversationId);
     if (truncationSummary.changed) {
       costLog.debug(
@@ -11752,29 +11926,39 @@ ${textContent}` };
                 span.setStatus({ code: SpanStatusCode.OK });
                 span.end();
               }
-              const serialized = JSON.stringify(result2.output ?? null);
-              const outputTokenEstimate = Math.ceil(serialized.length / 4);
+              const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result2.output);
+              const strippedSerialized = JSON.stringify(strippedOutput ?? null);
+              const guarded = await this.guardOversizedToolResult({
+                tenantId: input.tenantId ?? "__default__",
+                toolName: result2.tool,
+                toolCallId: result2.callId,
+                output: strippedOutput,
+                serialized: strippedSerialized,
+                policy: spillPolicy
+              });
+              const effectiveOutput = guarded ?? strippedOutput ?? null;
+              const effectiveSerialized = guarded ? JSON.stringify(guarded) : strippedSerialized;
+              const outputTokenEstimate = Math.ceil(effectiveSerialized.length / 4);
               toolOutputEstimateSinceModel += outputTokenEstimate;
               yield pushEvent({
                 type: "tool:completed",
                 tool: result2.tool,
                 toolCallId: result2.callId,
                 input: callInputMap.get(result2.callId),
-                output: result2.output,
+                output: effectiveOutput,
                 duration: now() - batchStart,
                 outputTokenEstimate
               });
-              const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result2.output);
               toolResultsForModel.push({
                 type: "tool_result",
                 tool_use_id: result2.callId,
                 tool_name: result2.tool,
-                content: JSON.stringify(strippedOutput ?? null)
+                content: effectiveSerialized
               });
               {
                 const archive = this.archivedToolResultsByConversation.get(conversationId);
                 if (archive && !NON_ARCHIVABLE_TOOL_NAMES.has(result2.tool)) {
-                  const payload = JSON.stringify(result2.output ?? null);
+                  const payload = effectiveSerialized;
                   archive[result2.callId] = {
                     toolResultId: result2.callId,
                     conversationId,
@@ -11795,7 +11979,7 @@ ${textContent}` };
                   output: {
                     type: "content",
                     value: [
-                      { type: "text", text: JSON.stringify(strippedOutput ?? null) },
+                      { type: "text", text: effectiveSerialized },
                       ...mediaItems
                     ]
                   }
@@ -11805,7 +11989,7 @@ ${textContent}` };
                   type: "tool-result",
                   toolCallId: result2.callId,
                   toolName: result2.tool,
-                  output: { type: "json", value: result2.output ?? null }
+                  output: { type: "json", value: effectiveOutput }
                 });
               }
             }
@@ -14654,7 +14838,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 +14912,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.15",
   "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

@@ -30,6 +30,14 @@ import {
   createReminderStoreFromEngine,
 } from "./storage/store-adapters.js";
 import { BashEnvironmentManager } from "./vfs/bash-manager.js";
+import {
+  type ToolResultSpillPolicy,
+  readSpillPolicy,
+  isOversizedToolResult,
+  formatSpillPayload,
+  buildSpillHandle,
+  buildInlineTruncation,
+} from "./tool-result-guard.js";
 import type { VirtualMount } from "./vfs/poncho-fs-adapter.js";
 export type { VirtualMount } from "./vfs/poncho-fs-adapter.js";
 import { createBashTool } from "./vfs/bash-tool.js";
@@ -65,6 +73,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 +974,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 +1028,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);
     }
@@ -1172,6 +1189,77 @@ export class AgentHarness {
     return merged;
   }
 
+  /**
+   * Guard a single FRESH tool result against overflowing the context window.
+   * `serialized` is the JSON-serialized (media-stripped) output. Returns a
+   * replacement value to put in front of the model (a handle or a truncated
+   * preview) when the result is oversized, or `null` to leave it untouched.
+   * Spilling writes the full payload to a VFS file; on any write failure it
+   * falls back to inline truncation, so this never throws into the run loop.
+   */
+  private async guardOversizedToolResult(opts: {
+    tenantId: string;
+    toolName: string;
+    toolCallId: string;
+    output: unknown;
+    serialized: string;
+    policy: ToolResultSpillPolicy;
+  }): Promise<Record<string, unknown> | null> {
+    const { tenantId, toolName, toolCallId, output, serialized, policy } = opts;
+    if (!isOversizedToolResult(serialized, policy)) return null;
+
+    if (policy.enabled && this.bashManager) {
+      try {
+        const vfs = this.createVfsAccess(tenantId);
+        const { content, format, records } = formatSpillPayload(output);
+        // toolCallId is unique per call and stable across a checkpoint→resume,
+        // so the path is idempotent (a resumed run rewrites the same file).
+        const safeTool = toolName.replace(/[^A-Za-z0-9_-]/g, "_");
+        const path = `${policy.dir}/${safeTool}_${toolCallId}.${format}`;
+        await vfs.mkdir(policy.dir, { recursive: true });
+        await vfs.writeText(path, content);
+        await this.pruneSpillDir(vfs, policy.dir, policy.keepLast);
+        return buildSpillHandle({ toolName, path, format, serialized, records });
+      } catch {
+        // Fall through to inline truncation below.
+      }
+    }
+
+    return buildInlineTruncation(toolName, serialized);
+  }
+
+  /** Best-effort: keep only the newest `keepLast` files in the spill dir. */
+  private async pruneSpillDir(
+    vfs: NonNullable<ToolContext["vfs"]>,
+    dir: string,
+    keepLast: number,
+  ): Promise<void> {
+    try {
+      const entries = await vfs.readdir(dir);
+      const names = (Array.isArray(entries) ? entries : [])
+        .map((e) => (typeof e === "string" ? e : (e as { name?: string }).name))
+        .filter((n): n is string => typeof n === "string");
+      if (names.length <= keepLast) return;
+      const stated = await Promise.all(
+        names.map(async (name) => {
+          try {
+            const s = await vfs.stat(`${dir}/${name}`);
+            return { name, mtime: s.updatedAt ?? 0 };
+          } catch {
+            return { name, mtime: 0 };
+          }
+        }),
+      );
+      stated.sort((a, b) => a.mtime - b.mtime); // oldest first
+      const doomed = stated.slice(0, stated.length - keepLast);
+      for (const d of doomed) {
+        try { await vfs.rm(`${dir}/${d.name}`); } catch { /* best-effort */ }
+      }
+    } catch {
+      // Dir unreadable — nothing to prune.
+    }
+  }
+
   private truncateHistoricalToolResults(
     messages: Message[],
     conversationId: string,
@@ -2203,6 +2291,7 @@ export class AgentHarness {
     const messages: Message[] = [...(input.messages ?? [])];
     const conversationId = input.conversationId ?? "__default__";
     this.seedToolResultArchive(conversationId, input.parameters);
+    const spillPolicy = readSpillPolicy(input.parameters);
     const truncationSummary = this.truncateHistoricalToolResults(messages, conversationId);
     if (truncationSummary.changed) {
       costLog.debug(
@@ -3683,30 +3772,49 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
             span.setStatus({ code: SpanStatusCode.OK });
             span.end();
           }
-          const serialized = JSON.stringify(result.output ?? null);
-          const outputTokenEstimate = Math.ceil(serialized.length / 4);
+          // Separate inline media (images/PDFs) from the textual output, then
+          // guard the textual part against overflowing the window. A single
+          // oversized fresh result is replaced with a handle (spill) or a
+          // preview (inline) BEFORE we emit the event or feed the model — so
+          // neither the WS stream nor the next step ever carries the full
+          // multi-MB payload.
+          const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result.output);
+          const strippedSerialized = JSON.stringify(strippedOutput ?? null);
+          const guarded = await this.guardOversizedToolResult({
+            tenantId: input.tenantId ?? "__default__",
+            toolName: result.tool,
+            toolCallId: result.callId,
+            output: strippedOutput,
+            serialized: strippedSerialized,
+            policy: spillPolicy,
+          });
+          const effectiveOutput: unknown = guarded ?? strippedOutput ?? null;
+          const effectiveSerialized = guarded ? JSON.stringify(guarded) : strippedSerialized;
+          const outputTokenEstimate = Math.ceil(effectiveSerialized.length / 4);
           toolOutputEstimateSinceModel += outputTokenEstimate;
           yield pushEvent({
             type: "tool:completed",
             tool: result.tool,
             toolCallId: result.callId,
             input: callInputMap.get(result.callId),
-            output: result.output,
+            output: effectiveOutput,
             duration: now() - batchStart,
             outputTokenEstimate,
           });
 
-          const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result.output);
           toolResultsForModel.push({
             type: "tool_result",
             tool_use_id: result.callId,
             tool_name: result.tool,
-            content: JSON.stringify(strippedOutput ?? null),
+            content: effectiveSerialized,
           });
           {
             const archive = this.archivedToolResultsByConversation.get(conversationId);
             if (archive && !NON_ARCHIVABLE_TOOL_NAMES.has(result.tool)) {
-              const payload = JSON.stringify(result.output ?? null);
+              // Archive the model-visible payload (handle/preview when guarded).
+              // When spilled, the VFS file is the durable full copy; keeping the
+              // in-memory archive small avoids re-introducing the same bloat.
+              const payload = effectiveSerialized;
               archive[result.callId] = {
                 toolResultId: result.callId,
                 conversationId,
@@ -3728,7 +3836,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
               output: {
                 type: "content",
                 value: [
-                  { type: "text", text: JSON.stringify(strippedOutput ?? null) },
+                  { type: "text", text: effectiveSerialized },
                   ...mediaItems,
                 ],
               },
@@ -3738,7 +3846,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
               type: "tool-result",
               toolCallId: result.callId,
               toolName: result.tool,
-              output: { type: "json", value: result.output ?? null },
+              output: { type: "json", value: effectiveOutput },
             });
           }
         }

package/src/tool-result-guard.ts

@@ -0,0 +1,133 @@
+// Oversized FRESH tool-result guard — pure logic.
+//
+// `truncateHistoricalToolResults` (in harness.ts) only shrinks results from
+// PRIOR runs — it deliberately preserves the latest run's results so the model
+// can read what it just fetched. So a single fresh result that is itself larger
+// than the context window is never truncated, and the next step fails with
+// "prompt is too long" (seen with MCP email-fetch tools returning 1.6M–3.3M
+// token payloads). This module decides what to put in front of the model when
+// that happens; the I/O (the VFS write + prune) lives on the Harness class,
+// which has the per-tenant filesystem. Splitting the pure decision out keeps it
+// unit-testable without a Harness instance.
+
+/** Run parameter key carrying the spill policy (a freeform-params bag entry,
+ *  same mechanism as `__toolResultArchive`). */
+export const SPILL_POLICY_PARAM = "__toolResultSpill";
+
+/** Results whose serialized form exceeds this many chars are guarded. ~125k
+ *  tokens — well under any current window, well above any normal result, so
+ *  normal-sized results are never touched. */
+export const DEFAULT_OVERSIZED_TOOL_RESULT_CHARS = 500_000;
+/** Preview kept inline when SPILLING — small, because the full payload is in
+ *  the file. */
+export const SPILLED_PREVIEW_CHARS = 6_000;
+/** Preview kept inline when TRUNCATING — larger, because there's no file to
+ *  fall back to. */
+export const INLINE_TRUNCATE_PREVIEW_CHARS = 60_000;
+export const DEFAULT_SPILL_DIR = "/tmp/tool-results";
+export const DEFAULT_SPILL_KEEP_LAST = 20;
+
+export interface ToolResultSpillPolicy {
+  enabled: boolean;
+  dir: string;
+  thresholdChars: number;
+  keepLast: number;
+}
+
+/** Parse the spill policy out of the run parameters, applying defaults. A
+ *  missing/malformed bag yields a disabled policy with safe defaults. */
+export const readSpillPolicy = (
+  parameters: Record<string, unknown> | undefined,
+): ToolResultSpillPolicy => {
+  const raw = parameters?.[SPILL_POLICY_PARAM];
+  const obj = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
+  const thresholdChars =
+    typeof obj.thresholdChars === "number" && obj.thresholdChars > 0
+      ? obj.thresholdChars
+      : DEFAULT_OVERSIZED_TOOL_RESULT_CHARS;
+  const dir =
+    typeof obj.dir === "string" && obj.dir.startsWith("/") ? obj.dir : DEFAULT_SPILL_DIR;
+  const keepLast =
+    typeof obj.keepLast === "number" && obj.keepLast > 0
+      ? Math.floor(obj.keepLast)
+      : DEFAULT_SPILL_KEEP_LAST;
+  return { enabled: obj.enabled === true, dir, thresholdChars, keepLast };
+};
+
+/** True when this serialized result is large enough to need guarding. */
+export const isOversizedToolResult = (
+  serialized: string,
+  policy: ToolResultSpillPolicy,
+): boolean => serialized.length > policy.thresholdChars;
+
+/** Serialize an oversized payload for the spill file. Arrays become JSONL (one
+ *  record per line — bash/jq/sed friendly, line ranges map to records); other
+ *  shapes become pretty JSON. */
+export const formatSpillPayload = (
+  output: unknown,
+): { content: string; format: "jsonl" | "json"; records?: number } => {
+  if (Array.isArray(output)) {
+    return {
+      content: output.map((row) => JSON.stringify(row)).join("\n"),
+      format: "jsonl",
+      records: output.length,
+    };
+  }
+  return { content: JSON.stringify(output ?? null, null, 2), format: "json" };
+};
+
+/** The handle object placed in front of the model when a result is spilled to
+ *  a file: a small preview plus the path and bash-readback instructions. */
+export const buildSpillHandle = (opts: {
+  toolName: string;
+  path: string;
+  format: "jsonl" | "json";
+  serialized: string;
+  records?: number;
+}): Record<string, unknown> => {
+  const { toolName, path, format, serialized, records } = opts;
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const isArray = format === "jsonl";
+  return {
+    __toolResultSpilled: true,
+    tool: toolName,
+    path,
+    format,
+    ...(records !== undefined ? { records } : {}),
+    totalChars: serialized.length,
+    approxTokens,
+    preview: serialized.slice(0, SPILLED_PREVIEW_CHARS),
+    note:
+      `This result was too large to return inline (~${approxTokens.toLocaleString()} ` +
+      `tokens) and was saved to ${path}. Inspect it with bash — e.g. ` +
+      `\`wc -l ${path}\`, \`head -c 4000 ${path}\`, ` +
+      (isArray
+        ? `\`sed -n '1,5p' ${path}\`, \`grep -i <term> ${path}\`, or \`jq\` per line`
+        : `\`grep -i <term> ${path}\``) +
+      `. Do NOT cat or read_file the whole file (it re-overflows). Or re-run the ` +
+      `tool with a narrower request (fewer items / a filter / metadata only).`,
+  };
+};
+
+/** The replacement placed in front of the model when a result is too large and
+ *  spill is unavailable: a preview plus a "re-run narrower" instruction. */
+export const buildInlineTruncation = (
+  toolName: string,
+  serialized: string,
+): Record<string, unknown> => {
+  const approxTokens = Math.ceil(serialized.length / 4);
+  const omittedChars = Math.max(0, serialized.length - INLINE_TRUNCATE_PREVIEW_CHARS);
+  return {
+    __toolResultTruncated: true,
+    tool: toolName,
+    approxTokens,
+    omittedChars,
+    preview: serialized.slice(0, INLINE_TRUNCATE_PREVIEW_CHARS),
+    note:
+      `This result was too large (~${approxTokens.toLocaleString()} tokens) and was ` +
+      `truncated to fit the context window — only the first ` +
+      `${INLINE_TRUNCATE_PREVIEW_CHARS.toLocaleString()} characters are shown. Re-run ` +
+      `with a narrower request (fewer items / a filter / metadata only). Do NOT retry ` +
+      `the same call unchanged — it will overflow again.`,
+  };
+};

package/test/tool-result-guard.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_OVERSIZED_TOOL_RESULT_CHARS,
+  DEFAULT_SPILL_DIR,
+  DEFAULT_SPILL_KEEP_LAST,
+  INLINE_TRUNCATE_PREVIEW_CHARS,
+  SPILLED_PREVIEW_CHARS,
+  buildInlineTruncation,
+  buildSpillHandle,
+  formatSpillPayload,
+  isOversizedToolResult,
+  readSpillPolicy,
+} from "../src/tool-result-guard.js";
+
+describe("readSpillPolicy", () => {
+  it("defaults to disabled with safe defaults when the param is absent", () => {
+    expect(readSpillPolicy(undefined)).toEqual({
+      enabled: false,
+      dir: DEFAULT_SPILL_DIR,
+      thresholdChars: DEFAULT_OVERSIZED_TOOL_RESULT_CHARS,
+      keepLast: DEFAULT_SPILL_KEEP_LAST,
+    });
+  });
+
+  it("defaults when the param is malformed", () => {
+    expect(readSpillPolicy({ __toolResultSpill: "nope" }).enabled).toBe(false);
+    expect(readSpillPolicy({ __toolResultSpill: 42 }).dir).toBe(DEFAULT_SPILL_DIR);
+  });
+
+  it("reads enabled + dir + threshold + keepLast", () => {
+    const p = readSpillPolicy({
+      __toolResultSpill: { enabled: true, dir: "/tmp/x", thresholdChars: 1000, keepLast: 5 },
+    });
+    expect(p).toEqual({ enabled: true, dir: "/tmp/x", thresholdChars: 1000, keepLast: 5 });
+  });
+
+  it("rejects a non-absolute dir, a non-positive threshold, and a bad keepLast", () => {
+    const p = readSpillPolicy({
+      __toolResultSpill: { enabled: true, dir: "relative", thresholdChars: 0, keepLast: -3 },
+    });
+    expect(p.dir).toBe(DEFAULT_SPILL_DIR);
+    expect(p.thresholdChars).toBe(DEFAULT_OVERSIZED_TOOL_RESULT_CHARS);
+    expect(p.keepLast).toBe(DEFAULT_SPILL_KEEP_LAST);
+  });
+
+  it("only treats enabled === true as enabled (not truthy strings)", () => {
+    expect(readSpillPolicy({ __toolResultSpill: { enabled: "yes" } }).enabled).toBe(false);
+    expect(readSpillPolicy({ __toolResultSpill: { enabled: 1 } }).enabled).toBe(false);
+  });
+});
+
+describe("isOversizedToolResult", () => {
+  const policy = readSpillPolicy({ __toolResultSpill: { enabled: true, thresholdChars: 100 } });
+  it("is false at or below the threshold (boundary)", () => {
+    expect(isOversizedToolResult("a".repeat(100), policy)).toBe(false);
+    expect(isOversizedToolResult("a".repeat(99), policy)).toBe(false);
+  });
+  it("is true above the threshold", () => {
+    expect(isOversizedToolResult("a".repeat(101), policy)).toBe(true);
+  });
+});
+
+describe("formatSpillPayload", () => {
+  it("formats an array as JSONL with a record count", () => {
+    const r = formatSpillPayload([{ a: 1 }, { b: 2 }, { c: 3 }]);
+    expect(r.format).toBe("jsonl");
+    expect(r.records).toBe(3);
+    expect(r.content.split("\n")).toEqual(['{"a":1}', '{"b":2}', '{"c":3}']);
+  });
+
+  it("formats a non-array as pretty JSON with no record count", () => {
+    const r = formatSpillPayload({ hello: "world" });
+    expect(r.format).toBe("json");
+    expect(r.records).toBeUndefined();
+    expect(r.content).toBe('{\n  "hello": "world"\n}');
+  });
+
+  it("handles null", () => {
+    expect(formatSpillPayload(null)).toEqual({ content: "null", format: "json" });
+  });
+});
+
+describe("buildSpillHandle", () => {
+  it("returns a handle with path, format, records, preview, and bash instructions", () => {
+    const serialized = "x".repeat(SPILLED_PREVIEW_CHARS + 50_000);
+    const h = buildSpillHandle({
+      toolName: "mcp_gmail_GMAIL_FETCH_EMAILS",
+      path: "/tmp/tool-results/mcp_gmail_GMAIL_FETCH_EMAILS_tool_1.jsonl",
+      format: "jsonl",
+      serialized,
+      records: 312,
+    });
+    expect(h.__toolResultSpilled).toBe(true);
+    expect(h.records).toBe(312);
+    expect(h.totalChars).toBe(serialized.length);
+    expect((h.preview as string).length).toBe(SPILLED_PREVIEW_CHARS);
+    expect(String(h.note)).toContain("/tmp/tool-results/");
+    expect(String(h.note)).toContain("jq"); // array → jsonl hint
+    expect(String(h.note)).toContain("Do NOT cat");
+  });
+
+  it("omits the array-only jq hint and records for json format", () => {
+    const h = buildSpillHandle({
+      toolName: "t",
+      path: "/tmp/tool-results/t_x.json",
+      format: "json",
+      serialized: "y".repeat(10),
+    });
+    expect(h.records).toBeUndefined();
+    expect(String(h.note)).not.toContain("jq");
+  });
+});
+
+describe("buildInlineTruncation", () => {
+  it("returns a truncation marker with a capped preview and omitted-char count", () => {
+    const serialized = "z".repeat(INLINE_TRUNCATE_PREVIEW_CHARS + 1234);
+    const t = buildInlineTruncation("some_tool", serialized);
+    expect(t.__toolResultTruncated).toBe(true);
+    expect((t.preview as string).length).toBe(INLINE_TRUNCATE_PREVIEW_CHARS);
+    expect(t.omittedChars).toBe(1234);
+    expect(String(t.note)).toContain("Do NOT retry");
+  });
+});