@namzu/sdk 34.2.0 → 36.0.0

package/dist/tools/coordinator/ask-user-question.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The one tool that turns a run around to face the human.
+ *
+ * It used to be built inside `buildCoordinatorTools`, which needs a gateway,
+ * a scheduler and a roster the question has no use for — so a host that
+ * wanted only this tool (an interactive terminal with no delegation) had to
+ * assemble the whole coordinator set and fish the question out of it, and
+ * had to invent a run id at build time because the builder demanded one.
+ * This builder needs the park handler and nothing else; the run id is read
+ * from the calling `ToolContext` unless the host pins one.
+ */
+import type { PendingAnswers, QuestionParkRecorder } from '../../runtime/query/question-park.js';
+import type { ResumeHandler } from '../../types/hitl/index.js';
+import type { RunId } from '../../types/ids/index.js';
+import type { ToolDefinition } from '../../types/tool/index.js';
+/** Internal identity shared by the builder and the agent authority boundary. */
+export declare const ASK_USER_QUESTION_TOOL_NAME: "ask_user_question";
+export interface AskUserQuestionToolOptions {
+    /** Where the question goes; the run parks on it until an answer comes back. */
+    resumeHandler: ResumeHandler;
+    /**
+     * The run the park is recorded against. Omit it and the tool uses the
+     * `runId` of the call that asked, which is the right run in every case
+     * but a host that answers questions for a run other than the one it drives.
+     */
+    runId?: RunId;
+    /** See the same field on `CoordinatorToolsOptions`. */
+    questionParks?: QuestionParkRecorder;
+    /** See the same field on `CoordinatorToolsOptions`. */
+    pendingAnswers?: PendingAnswers;
+}
+export declare function buildAskUserQuestionTool(config: AskUserQuestionToolOptions): ToolDefinition;
+//# sourceMappingURL=ask-user-question.d.ts.map

package/dist/tools/coordinator/ask-user-question.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user-question.d.ts","sourceRoot":"","sources":["../../../src/tools/coordinator/ask-user-question.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAA;AAChG,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAI/D,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,EAAG,mBAA4B,CAAA;AAuDvE,MAAM,WAAW,0BAA0B;IAC1C,+EAA+E;IAC/E,aAAa,EAAE,aAAa,CAAA;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,uDAAuD;IACvD,aAAa,CAAC,EAAE,oBAAoB,CAAA;IACpC,uDAAuD;IACvD,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,0BAA0B,GAAG,cAAc,CAgM3F"}

package/dist/tools/coordinator/ask-user-question.js

@@ -0,0 +1,237 @@
+/**
+ * The one tool that turns a run around to face the human.
+ *
+ * It used to be built inside `buildCoordinatorTools`, which needs a gateway,
+ * a scheduler and a roster the question has no use for — so a host that
+ * wanted only this tool (an interactive terminal with no delegation) had to
+ * assemble the whole coordinator set and fish the question out of it, and
+ * had to invent a run id at build time because the builder demanded one.
+ * This builder needs the park handler and nothing else; the run id is read
+ * from the calling `ToolContext` unless the host pins one.
+ */
+import { z } from 'zod';
+import { generateCheckpointId } from '../../utils/id.js';
+import { defineTool } from '../defineTool.js';
+/** Internal identity shared by the builder and the agent authority boundary. */
+export const ASK_USER_QUESTION_TOOL_NAME = 'ask_user_question';
+/**
+ * The single closed shape a capable provider constrains this call to.
+ *
+ * `options` arriving as a STRING is the failure this exists for: a model that
+ * serializes the array once tends to keep doing it, and the parse error it
+ * gets back never says the array was the problem.
+ * `additionalProperties: false` turns that into a refusal at generation time
+ * rather than a rejection after the fact.
+ */
+const askUserQuestionModelInputSchema = {
+    type: 'object',
+    properties: {
+        question: {
+            type: 'string',
+            description: 'Full question text — clear, specific, and ending with a question mark.',
+        },
+        header: {
+            type: 'string',
+            description: 'Optional very short topic label, no more than 24 characters.',
+        },
+        options: {
+            type: 'array',
+            description: 'A JSON array of 2-4 genuinely distinct, context-derived option objects.',
+            items: {
+                type: 'object',
+                properties: {
+                    label: {
+                        type: 'string',
+                        description: 'Concise option label. Put the recommended option first and append " (Recommended)".',
+                    },
+                    description: {
+                        type: 'string',
+                        description: 'Optional one-line explanation of what changes if selected.',
+                    },
+                },
+                required: ['label'],
+                additionalProperties: false,
+            },
+        },
+        multiSelect: {
+            type: 'boolean',
+            description: 'True only when several options can apply at once.',
+        },
+        allowFreeText: {
+            type: 'boolean',
+            description: 'Whether the user may answer in their own words.',
+        },
+    },
+    required: ['question', 'options'],
+    additionalProperties: false,
+};
+export function buildAskUserQuestionTool(config) {
+    const parkHandler = config.resumeHandler;
+    const { questionParks, pendingAnswers } = config;
+    return defineTool({
+        name: ASK_USER_QUESTION_TOOL_NAME,
+        description: 'Ask the user ONE question ONLY when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask "Who is the audience?" with options like Board / Engineering team / Customer); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. Put your recommended option FIRST and append " (Recommended)" to its label. Set multiSelect: true only when several options can apply at once. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Ask ONE question per call and prefer at most one question per assistant turn; if several decisions block you, ask only the ones that materially change your next actions, in sequence — most work needs at most 2-3 questions, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answer arrives as this tool\'s result; if the result says the user did not answer, do not ask this or any other question again — proceed on your best judgment without assuming consent.',
+        inputSchema: z
+            .object({
+            question: z
+                .string()
+                .min(1)
+                .describe('Full question text — clear, specific, ends with a question mark.'),
+            header: z
+                .string()
+                .max(24)
+                .optional()
+                .describe('Very short topic label for the question (e.g. "Audience", "Auth method").'),
+            options: z
+                .array(z
+                .object({
+                label: z
+                    .string()
+                    .min(1)
+                    .max(80)
+                    .describe('Concise option label (1-5 words). Recommended option goes first with " (Recommended)" appended.'),
+                description: z
+                    .string()
+                    .max(300)
+                    .optional()
+                    .describe('One line on what practically changes if this option is chosen.'),
+            })
+                .strict())
+                .min(2)
+                .max(4)
+                .describe('2-4 genuinely distinct, context-derived options.'),
+            multiSelect: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('True only when several options can apply at once.'),
+            allowFreeText: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('Whether the user may answer in their own words.'),
+        })
+            .strict(),
+        modelInputSchema: structuredClone(askUserQuestionModelInputSchema),
+        enforceModelInput: true,
+        validationErrorHint: 'Required shape: {"question":"...?","options":[{"label":"First (Recommended)","description":"What changes"},{"label":"Second","description":"What changes"}]}. "options" must be a JSON array of 2-4 objects, never a string.',
+        category: 'custom',
+        permissions: [],
+        readOnly: true,
+        destructive: false,
+        // MUST stay false: the executor serializes non-concurrency-safe
+        // tools in a single chain, so N question blocks in one assistant
+        // turn park strictly one-at-a-time. Hosts key their park/resolve
+        // registries by runId — concurrent parks on one run clobber each
+        // other and the first promise never resolves (run hangs to TTL).
+        concurrencySafe: false,
+        async execute({ question, header, options, multiSelect, allowFreeText }, context) {
+            const toolUseId = context.toolUseId;
+            if (!toolUseId) {
+                // Without the executing tool_use_id the question has no
+                // stable identity: the host could never merge the awaiting
+                // card with its resolution, and answers could not be matched
+                // back. Hard-fail instead of parking an unmergeable id.
+                return {
+                    success: false,
+                    output: '',
+                    error: 'ask_user_question requires an executor that threads ToolContext.toolUseId; the question cannot be tracked without it.',
+                };
+            }
+            const questionOptions = options.map((opt, i) => ({
+                id: `opt_${i + 1}`,
+                label: opt.label,
+                ...(opt.description !== undefined ? { description: opt.description } : {}),
+            }));
+            const questionData = {
+                questionId: toolUseId,
+                question,
+                ...(header !== undefined ? { header } : {}),
+                options: questionOptions,
+                multiSelect,
+                allowFreeText,
+            };
+            // An answer carried in from a resumed run. Checked before the
+            // park, because re-entering this tool is HOW the answer gets
+            // delivered: the batch is re-executed, and without this the
+            // re-execution would ask the user something they already
+            // answered — or, headless, auto-answer with the no-consent
+            // sentinel and throw the real answer away.
+            const carried = pendingAnswers?.take(toolUseId);
+            // A real checkpoint, not a synthetic id nothing ever wrote.
+            // Skipped when an answer is already in hand: parking a
+            // question that is answered would leave an outstanding record
+            // for a decision that has been made.
+            const parkedAt = carried === undefined && questionParks ? await questionParks.record(questionData) : null;
+            const decision = carried ??
+                (await parkHandler({
+                    type: 'user_question',
+                    runId: config.runId ?? context.runId,
+                    // Provider correlation ids remain verbatim in questionData;
+                    // an unpersisted park gets its own safe checkpoint identifier.
+                    checkpointId: parkedAt ?? generateCheckpointId(),
+                    question: questionData,
+                }));
+            // Clear the park once the answer is in, so an approval queue
+            // stops serving a question that has been answered.
+            if (parkedAt !== null && questionParks) {
+                await questionParks.resolve(parkedAt, decision);
+            }
+            // The no-answer sentinel (explicitly NOT consent — fixes the
+            // "empty answer reads as approval" ambiguity): used for empty
+            // answers, misdirected legacy decisions (e.g. a stale replica
+            // resolving with approve/continue verbs), and answers that
+            // carry a different question's id.
+            const noAnswer = {
+                success: true,
+                output: 'The user did not answer this question. Do not assume a choice or consent; proceed on your best judgment or continue without this information.',
+                data: { question, answered: false },
+            };
+            if (decision.action === 'abort') {
+                return {
+                    success: false,
+                    output: 'The user declined to answer and asked to stop. Acknowledge briefly and end your turn.',
+                    data: { question, answered: false, declined: true },
+                };
+            }
+            if (decision.action !== 'answer_question')
+                return noAnswer;
+            if (decision.questionId !== undefined && decision.questionId !== toolUseId) {
+                // Misdirection guard: this answer was meant for a different
+                // question parked under the same run (stale client). Never
+                // fabricate a selection against the wrong question.
+                return noAnswer;
+            }
+            const stripRecommended = (label) => label.replace(/\s*\(recommended\)\s*$/i, '').trim();
+            const selected = decision.selectedOptionIds
+                .map((id) => questionOptions.find((opt) => opt.id === id))
+                .filter((opt) => opt !== undefined)
+                .map((opt) => ({ id: opt.id, label: stripRecommended(opt.label) }));
+            const freeText = decision.freeText?.trim() ?? '';
+            if (selected.length === 0 && !freeText)
+                return noAnswer;
+            let output;
+            if (selected.length > 0) {
+                const joined = selected.map((s) => `"${s.label}"`).join(', ');
+                output = `User answered "${question}": ${joined}`;
+                if (freeText) {
+                    output += `\nAdditional note from the user: "${freeText}"`;
+                }
+            }
+            else {
+                output = `User answered "${question}" in their own words: "${freeText}"`;
+            }
+            return {
+                success: true,
+                output,
+                data: {
+                    question,
+                    selected,
+                    ...(freeText ? { freeText } : {}),
+                    answered: true,
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=ask-user-question.js.map

package/dist/tools/coordinator/ask-user-question.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user-question.js","sourceRoot":"","sources":["../../../src/tools/coordinator/ask-user-question.ts"],"names":[],"mappings":"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"}

package/dist/tools/coordinator/index.d.ts

@@ -7,6 +7,7 @@ import type { ResumeHandler } from '../../types/hitl/index.js';
 import type { RunId, TaskId } from '../../types/ids/index.js';
 import type { TaskStore } from '../../types/task/index.js';
 import type { ToolDefinition } from '../../types/tool/index.js';
+export { ASK_USER_QUESTION_TOOL_NAME } from './ask-user-question.js';
 export type TaskLaunchedCallback = (agentTaskId: TaskId, meta: {
     agentId: string;
     description: string;
@@ -83,8 +84,6 @@ export interface CoordinatorToolsOptions {
      */
     pendingAnswers?: PendingAnswers;
 }
-/** Internal identity shared by the builder and the agent authority boundary. */
-export declare const ASK_USER_QUESTION_TOOL_NAME: "ask_user_question";
 /**
  * How long a coordinator tool may wait on a delegated agent.
  *

package/dist/tools/coordinator/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/coordinator/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAA;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAS/D,MAAM,MAAM,oBAAoB,GAAG,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IACL,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B,KACG,IAAI,CAAA;AAET,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,aAAa,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAA;IACpC,eAAe,EAAE,MAAM,EAAE,CAAA;IAEzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAE3C,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,cAAc,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAA;IAE9C,cAAc,CAAC,EAAE,oBAAoB,CAAA;IAErC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;IAEjC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAE7B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAEpC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,EAAG,mBAA4B,CAAA;AAmRvE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,QAAiB,CAAA;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,QAAgE,CAAA;AA6B/F,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,uBAAuB,GAAG,cAAc,EAAE,CA0rCrF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/coordinator/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAA;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAO/D,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAA;AAIpE,MAAM,MAAM,oBAAoB,GAAG,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IACL,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B,KACG,IAAI,CAAA;AAET,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,aAAa,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,mBAAmB,CAAA;IACpC,eAAe,EAAE,MAAM,EAAE,CAAA;IAEzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAE3C,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,cAAc,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAA;IAE9C,cAAc,CAAC,EAAE,oBAAoB,CAAA;IAErC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;IAEjC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAE7B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAA;IAEpC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B;AA8ND;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,QAAiB,CAAA;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,QAAgE,CAAA;AA6B/F,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,uBAAuB,GAAG,cAAc,EAAE,CA6/BrF"}

package/dist/tools/coordinator/index.js

@@ -1,13 +1,13 @@
 import { z } from 'zod';
 import { toErrorMessage } from '../../utils/error.js';
-import { asCheckpointId, asTaskId } from '../../utils/id.js';
+import { asTaskId } from '../../utils/id.js';
 import { defineTool } from '../defineTool.js';
 import { wrapUntrusted } from '../untrusted-envelope.js';
+import { buildAskUserQuestionTool } from './ask-user-question.js';
 import { failureLabel, taskSucceeded } from './outcome.js';
+export { ASK_USER_QUESTION_TOOL_NAME } from './ask-user-question.js';
 import { resolvePlanDependencies } from './plan-dependencies.js';
 import { describeWaitTimeout, waitForTaskWithBounds } from './wait-with-idle-bound.js';
-/** Internal identity shared by the builder and the agent authority boundary. */
-export const ASK_USER_QUESTION_TOOL_NAME = 'ask_user_question';
 const approvePlanStepSchema = z.object({
     description: z.string().describe('What this step does'),
     agent_id: z
@@ -16,57 +16,6 @@ const approvePlanStepSchema = z.object({
         .describe('Which agent handles this (omit for orchestrator-owned steps)'),
     depends_on: z.array(z.string()).optional().describe('Step descriptions this depends on'),
 });
-/**
- * The single closed shape a capable provider constrains this call to.
- *
- * `options` arriving as a STRING is the failure this exists for: a model that
- * serializes the array once tends to keep doing it, and the parse error it
- * gets back never says the array was the problem.
- * `additionalProperties: false` turns that into a refusal at generation time
- * rather than a rejection after the fact.
- */
-const askUserQuestionModelInputSchema = {
-    type: 'object',
-    properties: {
-        question: {
-            type: 'string',
-            description: 'Full question text — clear, specific, and ending with a question mark.',
-        },
-        header: {
-            type: 'string',
-            description: 'Optional very short topic label, no more than 24 characters.',
-        },
-        options: {
-            type: 'array',
-            description: 'A JSON array of 2-4 genuinely distinct, context-derived option objects.',
-            items: {
-                type: 'object',
-                properties: {
-                    label: {
-                        type: 'string',
-                        description: 'Concise option label. Put the recommended option first and append " (Recommended)".',
-                    },
-                    description: {
-                        type: 'string',
-                        description: 'Optional one-line explanation of what changes if selected.',
-                    },
-                },
-                required: ['label'],
-                additionalProperties: false,
-            },
-        },
-        multiSelect: {
-            type: 'boolean',
-            description: 'True only when several options can apply at once.',
-        },
-        allowFreeText: {
-            type: 'boolean',
-            description: 'Whether the user may answer in their own words.',
-        },
-    },
-    required: ['question', 'options'],
-    additionalProperties: false,
-};
 /** One well-formed tag token: `<step>`, `</step>`, `<a href="…">`, `<br/>`. */
 const TAG_TOKEN = /<\/?[A-Za-z][\w-]*(?:\s[^<>]*)?\/?>/g;
 const DESCRIPTION_BLOCK = /<description>([\s\S]*?)<\/description>/gi;
@@ -1259,172 +1208,7 @@ export function buildCoordinatorTools(opts) {
         tools.push(updatePlanStep);
     }
     if (resumeHandler && runId) {
-        const parkRunId = runId;
-        const parkHandler = resumeHandler;
-        const askUserQuestion = defineTool({
-            name: ASK_USER_QUESTION_TOOL_NAME,
-            description: 'Ask the user ONE question ONLY when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask "Who is the audience?" with options like Board / Engineering team / Customer); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. Put your recommended option FIRST and append " (Recommended)" to its label. Set multiSelect: true only when several options can apply at once. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Ask ONE question per call and prefer at most one question per assistant turn; if several decisions block you, ask only the ones that materially change your next actions, in sequence — most work needs at most 2-3 questions, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answer arrives as this tool\'s result; if the result says the user did not answer, do not ask this or any other question again — proceed on your best judgment without assuming consent.',
-            inputSchema: z
-                .object({
-                question: z
-                    .string()
-                    .min(1)
-                    .describe('Full question text — clear, specific, ends with a question mark.'),
-                header: z
-                    .string()
-                    .max(24)
-                    .optional()
-                    .describe('Very short topic label for the question (e.g. "Audience", "Auth method").'),
-                options: z
-                    .array(z
-                    .object({
-                    label: z
-                        .string()
-                        .min(1)
-                        .max(80)
-                        .describe('Concise option label (1-5 words). Recommended option goes first with " (Recommended)" appended.'),
-                    description: z
-                        .string()
-                        .max(300)
-                        .optional()
-                        .describe('One line on what practically changes if this option is chosen.'),
-                })
-                    .strict())
-                    .min(2)
-                    .max(4)
-                    .describe('2-4 genuinely distinct, context-derived options.'),
-                multiSelect: z
-                    .boolean()
-                    .optional()
-                    .default(false)
-                    .describe('True only when several options can apply at once.'),
-                allowFreeText: z
-                    .boolean()
-                    .optional()
-                    .default(true)
-                    .describe('Whether the user may answer in their own words.'),
-            })
-                .strict(),
-            modelInputSchema: structuredClone(askUserQuestionModelInputSchema),
-            enforceModelInput: true,
-            validationErrorHint: 'Required shape: {"question":"...?","options":[{"label":"First (Recommended)","description":"What changes"},{"label":"Second","description":"What changes"}]}. "options" must be a JSON array of 2-4 objects, never a string.',
-            category: 'custom',
-            permissions: [],
-            readOnly: true,
-            destructive: false,
-            // MUST stay false: the executor serializes non-concurrency-safe
-            // tools in a single chain, so N question blocks in one assistant
-            // turn park strictly one-at-a-time. Hosts key their park/resolve
-            // registries by runId — concurrent parks on one run clobber each
-            // other and the first promise never resolves (run hangs to TTL).
-            concurrencySafe: false,
-            async execute({ question, header, options, multiSelect, allowFreeText }, context) {
-                const toolUseId = context.toolUseId;
-                if (!toolUseId) {
-                    // Without the executing tool_use_id the question has no
-                    // stable identity: the host could never merge the awaiting
-                    // card with its resolution, and answers could not be matched
-                    // back. Hard-fail instead of parking an unmergeable id.
-                    return {
-                        success: false,
-                        output: '',
-                        error: 'ask_user_question requires an executor that threads ToolContext.toolUseId; the question cannot be tracked without it.',
-                    };
-                }
-                const questionOptions = options.map((opt, i) => ({
-                    id: `opt_${i + 1}`,
-                    label: opt.label,
-                    ...(opt.description !== undefined ? { description: opt.description } : {}),
-                }));
-                const questionData = {
-                    questionId: toolUseId,
-                    question,
-                    ...(header !== undefined ? { header } : {}),
-                    options: questionOptions,
-                    multiSelect,
-                    allowFreeText,
-                };
-                // An answer carried in from a resumed run. Checked before the
-                // park, because re-entering this tool is HOW the answer gets
-                // delivered: the batch is re-executed, and without this the
-                // re-execution would ask the user something they already
-                // answered — or, headless, auto-answer with the no-consent
-                // sentinel and throw the real answer away.
-                const carried = pendingAnswers?.take(toolUseId);
-                // A real checkpoint, not a synthetic id nothing ever wrote.
-                // Skipped when an answer is already in hand: parking a
-                // question that is answered would leave an outstanding record
-                // for a decision that has been made.
-                const parkedAt = carried === undefined && questionParks ? await questionParks.record(questionData) : null;
-                const decision = carried ??
-                    (await parkHandler({
-                        type: 'user_question',
-                        runId: parkRunId,
-                        checkpointId: parkedAt ?? asCheckpointId(`cp_question_${toolUseId}`),
-                        question: questionData,
-                    }));
-                // Clear the park once the answer is in, so an approval queue
-                // stops serving a question that has been answered.
-                if (parkedAt !== null && questionParks) {
-                    await questionParks.resolve(parkedAt, decision);
-                }
-                // The no-answer sentinel (explicitly NOT consent — fixes the
-                // "empty answer reads as approval" ambiguity): used for empty
-                // answers, misdirected legacy decisions (e.g. a stale replica
-                // resolving with approve/continue verbs), and answers that
-                // carry a different question's id.
-                const noAnswer = {
-                    success: true,
-                    output: 'The user did not answer this question. Do not assume a choice or consent; proceed on your best judgment or continue without this information.',
-                    data: { question, answered: false },
-                };
-                if (decision.action === 'abort') {
-                    return {
-                        success: false,
-                        output: 'The user declined to answer and asked to stop. Acknowledge briefly and end your turn.',
-                        data: { question, answered: false, declined: true },
-                    };
-                }
-                if (decision.action !== 'answer_question')
-                    return noAnswer;
-                if (decision.questionId !== undefined && decision.questionId !== toolUseId) {
-                    // Misdirection guard: this answer was meant for a different
-                    // question parked under the same run (stale client). Never
-                    // fabricate a selection against the wrong question.
-                    return noAnswer;
-                }
-                const stripRecommended = (label) => label.replace(/\s*\(recommended\)\s*$/i, '').trim();
-                const selected = decision.selectedOptionIds
-                    .map((id) => questionOptions.find((opt) => opt.id === id))
-                    .filter((opt) => opt !== undefined)
-                    .map((opt) => ({ id: opt.id, label: stripRecommended(opt.label) }));
-                const freeText = decision.freeText?.trim() ?? '';
-                if (selected.length === 0 && !freeText)
-                    return noAnswer;
-                let output;
-                if (selected.length > 0) {
-                    const joined = selected.map((s) => `"${s.label}"`).join(', ');
-                    output = `User answered "${question}": ${joined}`;
-                    if (freeText) {
-                        output += `\nAdditional note from the user: "${freeText}"`;
-                    }
-                }
-                else {
-                    output = `User answered "${question}" in their own words: "${freeText}"`;
-                }
-                return {
-                    success: true,
-                    output,
-                    data: {
-                        question,
-                        selected,
-                        ...(freeText ? { freeText } : {}),
-                        answered: true,
-                    },
-                };
-            },
-        });
-        tools.push(askUserQuestion);
+        tools.push(buildAskUserQuestionTool({ resumeHandler, runId, questionParks, pendingAnswers }));
     }
     return tools;
 }