@vietor/agent-core 0.7.6 → 0.8.1

package/README.md

@@ -108,6 +108,7 @@ const session = await createSession({
 | `sessionId` | `string` | `randomUUID()` | Unique session identifier. |
 | `maxTurns` | `number` | `50` | Maximum agent turns (LLM calls with tool calls) per prompt before the run errors out. |
 | `stallThreshold` | `number` | `3` | Stall tolerance: consecutive identical tool-call sets, or consecutive text-only responses while todos are incomplete, before the run is treated as stalled. |
+| `maxParallelToolCalls` | `number` | `10` | Maximum number of tool calls executed concurrently in one turn. |
 
 The auto-compaction threshold is not configurable — it's derived internally as 75% of `llm.maxInputTokens` and exposed via `session.contextLimit`.
 
@@ -150,8 +151,41 @@ const session = await createSession({ systemPrompt, llm });
 | `exportState(): SessionState` | Return the full session state (`{ messages, todos }`) for the host to persist; `export()` returns only messages. |
 | `compact(): Promise<RunStatus>` | Ask the LLM to summarize the conversation so far, replacing history with a single summary message. Runs through the run loop — streams the summary and can be aborted via `abort()`. |
 | `abort(): void` | Abort the current prompt or compact, cancel pending tool calls, and dismiss unanswered user questions. |
-| `submitAnswer(id: string, answer: string): void` | Supply an answer to a pending user question (from the built-in AskUser tool). |
-| `pendingQuestion: Extract<TimelineEvent, { type: "question" }> \| undefined` | *(getter)* The most recent unanswered question, or `undefined` if none are pending. |
+| `submitAnswer(id: string, answers: AskAnswer[]): void` | Supply answers to a pending user question group (from the built-in AskUser tool), one entry per question; multi-select answers are `string[]`, skipped ones `""`. |
+| `pendingQuestion: Extract<TimelineEvent, { type: "question" }> \| undefined` | *(getter)* The most recent unanswered question group, or `undefined` if none are pending. |
+
+### Asking the user
+
+The built-in **AskUser** tool takes 1-4 questions in one call; each question has an optional `header` (≤ 12 chars), 2-4 `options` with optional `description`s, and an optional `multiSelect` flag:
+
+```ts
+{
+  questions: [
+    { header: "Deploy", question: "Which environment?", options: [{ label: "prod" }, { label: "staging" }], multiSelect: false },
+    { question: "Notify on?", options: [{ label: "email" }, { label: "slack" }], multiSelect: true },
+  ],
+}
+```
+
+The session emits one `question` timeline entry (also delivered via `onEvent`) — each item is an `AskedQuestion` (an `AskQuestion` plus an `answer` field, `null` while pending) — and pauses the run until answered:
+
+```ts
+{ type: "question", id: "q1", questions: [{ question: "Which environment?", options: [...], multiSelect: false, answer: null }, ...] }
+```
+
+The host renders the questions and supplies one answer per question via `submitAnswer` — `string` for single-select, `string[]` for multi-select, `""` to skip:
+
+```ts
+session.submitAnswer("q1", ["prod", ["email", "slack"]]);
+```
+
+The tool result fed back to the LLM is JSON keyed by question text; multi-select values are arrays of selected labels, skipped questions `""`:
+
+```json
+{ "Which environment?": "prod", "Notify on?": ["email", "slack"] }
+```
+
+`abort()` (or `dispose()`) resolves any pending question group with all-`""` answers and stops the run.
 
 ### Events
 
@@ -178,7 +212,7 @@ type TimelineEvent =
   | { type: "retry"; attempt: number; max: number; reason: string }
   | { type: "error"; text: string }
   | { type: "interrupted" }
-  | { type: "question"; id: string; text: string; options: string[]; answer: string | null }
+  | { type: "question"; id: string; questions: AskedQuestion[] }
   | { type: "notice"; text: string };
 ```
 
@@ -207,7 +241,7 @@ type StreamEvent =
 | `retry` | The LLM client retries after a transient API error. | ✓ |
 | `error` | An error occurred. | ✓ |
 | `interrupted` | The current run was aborted. | ✓ |
-| `question` | The AskUser tool poses a question. | ✓ |
+| `question` | The AskUser tool poses a group of 1-4 questions. | ✓ |
 | `notice` | `session.addNotice()` is called, or the run auto-compacts context. | ✓ |
 | `run_metrics` | Run metrics change: at run start, every second, and at run end (`running: false`). | — |
 
@@ -349,7 +383,7 @@ Also returned by `session.compact()` (`"ok"` on success, `"aborted"` if aborted,
 |---|---|
 | `result: string \| null` (`tool`) | `null` while the tool is running; the result text once `tool_end` arrives, or `"aborted"` if the run was interrupted. |
 | `isError?: boolean` / `resultSummary?: string` (`tool`) | Set when the tool ended with an error / a condensed summary of the result. |
-| `answer: string \| null` (`question`) | `null` until the user answers (via `submitAnswer` or `abort`). |
+| `questions: AskedQuestion[]` (`question`) | The question group; each item is an `AskQuestion` (`header?`, `question`, `options: {label, description?}[]`, `multiSelect`) with an `answer` field: `string` for single-select, `string[]` for multi-select, `""` when skipped; `null` until answered (via `submitAnswer` or `abort`). |
 
 ### `SessionMessage`
 
@@ -493,7 +527,7 @@ Interactive tools are **off by default** and registered only when explicitly ena
 
 | Tool | Description |
 |---|---|
-| **AskUser** | Ask the user a question and wait for the answer. |
+| **AskUser** | Ask the user 1-4 questions in one call (each with 2-4 options and optional multi-select) and wait for the answers. |
 | **TodoWrite** | Track multi-step task progress; the agent must complete every task before its final reply. |
 | **Skill** | Invoke a skill by name; loads its instructions into context. Registered automatically whenever `skills` are provided. |
 | **SubAgent** | Run a nested sub-agent: read-only "explore" investigation or "plan" implementation planning. Sub-agents are equipped with the session's read-only tools (FileRead/Glob/Grep/WebFetch, plus any custom tools marked `readOnly`). |

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { RunStatus } from "./runtime/agent.js";
 export type { SessionMessage } from "./runtime/session-messages.js";
 export { INITIAL_RUN_METRICS, type SessionEvent, type TimelineEvent, type RunMetrics } from "./runtime/events.js";
 export type { Tool, ToolContext, ToolSchema, Todo, TodoStatus, TextResult } from "./tools/types.js";
+export type { AskOption, AskQuestion, AskAnswer, AskedQuestion } from "./tools/ask-user.js";
 export { toolError } from "./tools/types.js";
 export type { BuiltinToolsOptions } from "./tools/registry.js";
 export type { Skill } from "./skills/types.js";

package/dist/runtime/agent.d.ts

@@ -14,6 +14,7 @@ export interface AgentOptions {
     getTodos: () => readonly Todo[];
     stallThreshold: number;
     maxTurns: number;
+    maxParallelToolCalls: number;
     contextLimit: number;
     resolveSkill?: (name: string) => Skill | undefined;
     onCompact?: () => void;
@@ -27,6 +28,7 @@ export declare class Agent {
     private getTodos;
     private stallThreshold;
     private maxTurns;
+    private maxParallelToolCalls;
     readonly contextLimit: number;
     private todoSnapshot;
     private resolveSkill?;

package/dist/runtime/agent.js

@@ -1,5 +1,5 @@
 import { isAbortError, mapWithConcurrency, withAbort } from "../util/async.js";
-import { MAX_PARALLEL_TOOL_CALLS, NOT_EXECUTED_PREFIX, SKILL_TOOL_NAME } from "../util/constants.js";
+import { NOT_EXECUTED_PREFIX, SKILL_TOOL_NAME } from "../util/constants.js";
 import { summarizeText, toErrorMessage } from "../util/text.js";
 import { parseToolArgs, toText } from "../llm/messages.js";
 import { SessionMessages } from "./session-messages.js";
@@ -14,6 +14,7 @@ export class Agent {
     getTodos;
     stallThreshold;
     maxTurns;
+    maxParallelToolCalls;
     contextLimit;
     todoSnapshot = [];
     resolveSkill;
@@ -30,6 +31,7 @@ export class Agent {
         this.getTodos = opts.getTodos;
         this.stallThreshold = opts.stallThreshold;
         this.maxTurns = opts.maxTurns;
+        this.maxParallelToolCalls = opts.maxParallelToolCalls;
         this.contextLimit = opts.contextLimit;
         this.resolveSkill = opts.resolveSkill;
         this.onCompact = opts.onCompact;
@@ -241,7 +243,7 @@ export class Agent {
         }
     }
     async runToolCalls(calls, onEvent, signal) {
-        const results = await mapWithConcurrency(calls, MAX_PARALLEL_TOOL_CALLS, (call) => this.executeToolCall(call, onEvent, signal), signal);
+        const results = await mapWithConcurrency(calls, this.maxParallelToolCalls, (call) => this.executeToolCall(call, onEvent, signal), signal);
         return signal?.aborted ? null : results;
     }
     async executeToolCall(call, onEvent, signal) {

package/dist/runtime/events.d.ts

@@ -1,3 +1,4 @@
+import type { AskedQuestion } from "../tools/ask-user.js";
 export interface RunMetrics {
     running: boolean;
     elapsed: number;
@@ -38,9 +39,7 @@ export type TimelineEvent = {
 } | {
     type: "question";
     id: string;
-    text: string;
-    options: string[];
-    answer: string | null;
+    questions: AskedQuestion[];
 } | {
     type: "notice";
     text: string;

package/dist/runtime/session.d.ts

@@ -4,6 +4,7 @@ import type { MCPServerConfig, MCPServerInfo } from "../mcp/types.js";
 import type { Skill } from "../skills/types.js";
 import { type BuiltinToolsOptions, type ToolRegistry } from "../tools/registry.js";
 import type { Todo, Tool } from "../tools/types.js";
+import type { AskAnswer } from "../tools/ask-user.js";
 import { type SessionEvent, type TimelineEvent } from "./events.js";
 import type { MCPClientInfo } from "../mcp/types.js";
 import { type RunStatus } from "./agent.js";
@@ -20,6 +21,7 @@ export interface SessionOptions {
     sessionId?: string;
     maxTurns?: number;
     stallThreshold?: number;
+    maxParallelToolCalls?: number;
 }
 export interface SessionDeps extends Omit<SessionOptions, "llm" | "tools" | "mcpServers"> {
     llm: LLMClient;
@@ -96,7 +98,7 @@ export declare class Session {
     importState(state: SessionState): void;
     compact(): Promise<RunStatus>;
     abort(): void;
-    submitAnswer(id: string, answer: string): void;
+    submitAnswer(id: string, answers: AskAnswer[]): void;
     prompt(text: string): Promise<PromptResult>;
     private ask;
 }

package/dist/runtime/session.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { isAbortError } from "../util/async.js";
 import { toErrorMessage } from "../util/text.js";
-import { DEFAULT_MAX_TURNS, DEFAULT_STALL_THRESHOLD } from "../util/constants.js";
+import { DEFAULT_MAX_PARALLEL_TOOL_CALLS, DEFAULT_MAX_TURNS, DEFAULT_STALL_THRESHOLD } from "../util/constants.js";
 import { registerBuiltinTools } from "../tools/registry.js";
 import { INITIAL_RUN_METRICS } from "./events.js";
 import { Agent } from "./agent.js";
@@ -77,17 +77,17 @@ class QuestionQueue {
         });
         return { id, promise };
     }
-    submit(id, answer) {
+    submit(id, answers) {
         const resolve = this.resolvers.get(id);
         if (resolve) {
             this.resolvers.delete(id);
-            resolve(answer);
+            resolve(answers);
         }
     }
-    resolveAll(answer) {
+    resolveAll() {
         const ids = [...this.resolvers.keys()];
         for (const id of ids) {
-            this.submit(id, answer);
+            this.submit(id, []);
         }
         return ids;
     }
@@ -200,7 +200,7 @@ export class Session {
         for (const s of deps.skills ?? [])
             this.skillsMap.set(s.name, s);
         registerBuiltinTools(this.tools, deps.builtInTools, {
-            ask: (q, o) => this.ask(q, o),
+            ask: (questions) => this.ask(questions),
             setTodos: (t) => this.todoStore.set(t),
             resolveSkill: deps.skills?.length ? this.resolveSkill : undefined,
             subAgent: {
@@ -210,6 +210,7 @@ export class Session {
                     cwd: this.cwd,
                     maxTurns: deps.maxTurns ?? DEFAULT_MAX_TURNS,
                     stallThreshold: deps.stallThreshold ?? DEFAULT_STALL_THRESHOLD,
+                    maxParallelToolCalls: deps.maxParallelToolCalls ?? DEFAULT_MAX_PARALLEL_TOOL_CALLS,
                     contextLimit: deps.contextLimit,
                     onUsage: (cacheInputTokens, missInputTokens, outputTokens) => this.agent.addUsage(cacheInputTokens, missInputTokens, outputTokens),
                 })(systemPrompt, task, signal),
@@ -224,6 +225,7 @@ export class Session {
             getTodos: () => this.todoStore.all,
             stallThreshold: deps.stallThreshold ?? DEFAULT_STALL_THRESHOLD,
             maxTurns: deps.maxTurns ?? DEFAULT_MAX_TURNS,
+            maxParallelToolCalls: deps.maxParallelToolCalls ?? DEFAULT_MAX_PARALLEL_TOOL_CALLS,
             contextLimit: deps.contextLimit,
             resolveSkill: this.resolveSkill,
             onCompact: () => {
@@ -356,21 +358,20 @@ export class Session {
     }
     abort() {
         this.abortController?.abort();
-        for (const id of this.questionQueue.resolveAll("")) {
-            this.timelineStore.setAnswer(id, "");
-        }
+        for (const id of this.questionQueue.resolveAll())
+            this.submitAnswer(id, []);
     }
-    submitAnswer(id, answer) {
-        this.questionQueue.submit(id, answer);
-        this.timelineStore.setAnswer(id, answer);
+    submitAnswer(id, answers) {
+        this.questionQueue.submit(id, answers);
+        this.timelineStore.setAnswers(id, answers);
     }
     async prompt(text) {
         this.rejectIfBusy();
         return this.start({ type: "user", text }, (signal) => this.agent.run(text, this.handleEvent, signal));
     }
-    ask(text, options) {
+    ask(questions) {
         const { id, promise } = this.questionQueue.ask();
-        this.emit({ type: "question", id, text, options, answer: null });
+        this.emit({ type: "question", id, questions: questions.map((q) => ({ ...q, answer: null })) });
         return promise;
     }
 }

package/dist/runtime/sub-agent-runner.d.ts

@@ -8,6 +8,7 @@ export interface SubAgentRunOptions {
     cwd: string;
     maxTurns: number;
     stallThreshold: number;
+    maxParallelToolCalls: number;
     contextLimit: number;
     onUsage?: (cacheInputTokens: number, missInputTokens: number, outputTokens: number) => void;
 }

package/dist/runtime/sub-agent-runner.js

@@ -16,6 +16,7 @@ export function createSubAgentRunner(opts) {
             getTodos: () => [],
             stallThreshold: opts.stallThreshold,
             maxTurns: opts.maxTurns,
+            maxParallelToolCalls: opts.maxParallelToolCalls,
             contextLimit: opts.contextLimit,
         });
         const status = await subAgent.run(task, undefined, signal);

package/dist/runtime/timeline.d.ts

@@ -1,5 +1,6 @@
 import type { SessionMessage } from "./session-messages.js";
 import type { SessionEvent, TimelineEvent } from "./events.js";
+import { type AskAnswer } from "../tools/ask-user.js";
 export declare class TimelineStore {
     private listeners;
     private entries;
@@ -10,7 +11,7 @@ export declare class TimelineStore {
     applyEvent(e: SessionEvent): void;
     private append;
     setResult(id: string, result: string, isError?: boolean, resultSummary?: string): void;
-    setAnswer(id: string, answer: string): void;
+    setAnswers(id: string, answers: AskAnswer[]): void;
     get latestUnansweredQuestion(): Extract<TimelineEvent, {
         type: "question";
     }> | undefined;

package/dist/runtime/timeline.js

@@ -1,4 +1,5 @@
 import { parseToolArgs, toText } from "../llm/messages.js";
+import { parseQuestions } from "../tools/ask-user.js";
 import { Emitter } from "../util/emitter.js";
 export class TimelineStore {
     listeners = new Emitter();
@@ -19,10 +20,6 @@ export class TimelineStore {
             case "tool_end":
                 this.setResult(e.id, e.result, e.isError, e.resultSummary);
                 break;
-            case "question":
-                this.pendingQuestions.set(e.id, this.entries.length);
-                this.append(e);
-                break;
             case "assistant_delta":
             case "thinking_delta":
             case "thinking_cleared":
@@ -37,6 +34,9 @@ export class TimelineStore {
         if (entry.type === "tool" && entry.result === null) {
             this.pendingTools.set(entry.id, this.entries.length - 1);
         }
+        else if (entry.type === "question") {
+            this.pendingQuestions.set(entry.id, this.entries.length - 1);
+        }
         this.listeners.notify();
     }
     setResult(id, result, isError, resultSummary) {
@@ -50,21 +50,24 @@ export class TimelineStore {
         this.entries[idx] = { ...entry, result, isError, resultSummary };
         this.listeners.notify();
     }
-    setAnswer(id, answer) {
+    setAnswers(id, answers) {
         const index = this.pendingQuestions.get(id);
         if (index === undefined)
             return;
         this.pendingQuestions.delete(id);
         const entry = this.entries[index];
-        if (entry.type !== "question" || entry.answer !== null)
+        if (entry.type !== "question" || entry.questions.some((q) => q.answer !== null))
             return;
-        this.entries[index] = { ...entry, answer };
+        this.entries[index] = {
+            ...entry,
+            questions: entry.questions.map((q, i) => ({ ...q, answer: answers[i] ?? "" })),
+        };
         this.listeners.notify();
     }
     get latestUnansweredQuestion() {
         for (let i = this.entries.length - 1; i >= 0; i--) {
             const e = this.entries[i];
-            if (e.type === "question" && e.answer === null)
+            if (e.type === "question" && e.questions.some((q) => q.answer === null))
                 return e;
         }
         return undefined;
@@ -138,6 +141,24 @@ export function toTimelineEntries(messages, summarizeArgs) {
                     else {
                         entries.push(entry);
                     }
+                    if (tc.function.name === "AskUser" && parsed.ok && result) {
+                        const { questions } = parseQuestions(parsed.args);
+                        if (questions.length > 0) {
+                            let answerMap = {};
+                            try {
+                                const parsedResult = JSON.parse(result.content);
+                                if (typeof parsedResult === "object" && parsedResult !== null) {
+                                    answerMap = parsedResult;
+                                }
+                            }
+                            catch { }
+                            entries.push({
+                                type: "question",
+                                id: tc.id,
+                                questions: questions.map((q) => ({ ...q, answer: answerMap[q.question] ?? "" })),
+                            });
+                        }
+                    }
                 }
             }
         }

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

@@ -1,3 +1,21 @@
 import type { Tool } from "./types.js";
-export declare const ASK_USER_GUIDANCE = "- When a decision belongs to the user, call AskUser and wait for the answer rather than listing options in prose. Ask when there are multiple reasonable approaches, an irreversible or consequential action, or the request is ambiguous. When you have enough information to proceed, act without asking.";
-export declare function createAskUserTool(ask: (question: string, options: string[]) => Promise<string>): Tool;
+export declare const ASK_USER_GUIDANCE = "- When a decision belongs to the user, call AskUser and wait for the answer rather than listing options in prose. Ask when there are multiple reasonable approaches, an irreversible or consequential action, or the request is ambiguous. When you have enough information to proceed, act without asking. Batch related questions into a single AskUser call (up to 4 questions, 2-4 options each).";
+export interface AskOption {
+    label: string;
+    description?: string;
+}
+export interface AskQuestion {
+    header?: string;
+    question: string;
+    options: AskOption[];
+    multiSelect: boolean;
+}
+export type AskAnswer = string | string[];
+export type AskedQuestion = AskQuestion & {
+    answer: AskAnswer | null;
+};
+export declare function parseQuestions(args: Record<string, unknown>): {
+    questions: AskQuestion[];
+    error?: string;
+};
+export declare function createAskUserTool(ask: (questions: AskQuestion[]) => Promise<AskAnswer[]>): Tool;

package/dist/tools/ask-user.js

@@ -1,6 +1,45 @@
 import { toolError } from "./types.js";
-export const ASK_USER_GUIDANCE = "- When a decision belongs to the user, call AskUser and wait for the answer rather than listing options in prose. Ask when there are multiple reasonable approaches, an irreversible or consequential action, or the request is ambiguous. When you have enough information to proceed, act without asking.";
-const DESCRIPTION = "Ask the user a question and wait for the answer. Provide at least one option. Returns the answer as text.";
+export const ASK_USER_GUIDANCE = "- When a decision belongs to the user, call AskUser and wait for the answer rather than listing options in prose. Ask when there are multiple reasonable approaches, an irreversible or consequential action, or the request is ambiguous. When you have enough information to proceed, act without asking. Batch related questions into a single AskUser call (up to 4 questions, 2-4 options each).";
+const MAX_QUESTIONS = 4;
+const MAX_OPTIONS = 4;
+const MAX_HEADER_LENGTH = 12;
+const DESCRIPTION = "Ask the user 1-4 questions and wait for the answers. Each question has an optional header (at most 12 chars), 2-4 options with optional descriptions, and an optional multiSelect flag. Returns JSON keyed by question text; multi-select answers are arrays of selected labels; skipped questions return an empty string. Do not add an 'Other' option — the user can always type a custom answer.";
+export function parseQuestions(args) {
+    const raw = args.questions;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { questions: [], error: `"questions" must be an array of 1-${MAX_QUESTIONS} question objects, got ${typeof raw}` };
+    }
+    if (raw.length > MAX_QUESTIONS) {
+        return { questions: [], error: `"questions" must contain at most ${MAX_QUESTIONS} questions, got ${raw.length}` };
+    }
+    const questions = [];
+    const seen = new Set();
+    for (const q of raw) {
+        if (!q)
+            return { questions: [], error: "each question must be an object" };
+        const question = typeof q.question === "string" ? q.question.trim() : "";
+        if (!question)
+            return { questions: [], error: "each question needs non-empty text" };
+        if (seen.has(question))
+            return { questions: [], error: "questions must be unique" };
+        seen.add(question);
+        const options = [];
+        if (!Array.isArray(q.options) || q.options.length < 2 || q.options.length > MAX_OPTIONS) {
+            return { questions: [], error: `each question needs 2-${MAX_OPTIONS} options` };
+        }
+        for (const o of q.options) {
+            if (!o)
+                return { questions: [], error: "each option must be an object" };
+            const label = typeof o.label === "string" ? o.label.trim() : "";
+            if (!label)
+                return { questions: [], error: "each option needs a non-empty label" };
+            options.push({ label, description: typeof o.description === "string" && o.description ? o.description : undefined });
+        }
+        const header = typeof q.header === "string" && q.header ? q.header.slice(0, MAX_HEADER_LENGTH) : undefined;
+        questions.push({ header, question, options, multiSelect: q.multiSelect === true });
+    }
+    return { questions };
+}
 export function createAskUserTool(ask) {
     return {
         name: "AskUser",
@@ -8,19 +47,54 @@ export function createAskUserTool(ask) {
         parameters: {
             type: "object",
             properties: {
-                question: { type: "string", description: "The question to ask the user." },
-                options: { type: "array", items: { type: "string" }, minItems: 1, description: "List of choices; at least one required." },
+                questions: {
+                    type: "array",
+                    description: "1-4 questions to ask the user, answered together.",
+                    minItems: 1,
+                    maxItems: MAX_QUESTIONS,
+                    items: {
+                        type: "object",
+                        properties: {
+                            header: { type: "string", maxLength: MAX_HEADER_LENGTH, description: "Short label for the question, shown as a chip." },
+                            question: { type: "string", description: "The question text." },
+                            options: {
+                                type: "array",
+                                minItems: 2,
+                                maxItems: MAX_OPTIONS,
+                                description: "2-4 mutually exclusive choices.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        label: { type: "string", description: "The choice label." },
+                                        description: { type: "string", description: "Optional detail shown under the label." },
+                                    },
+                                    required: ["label"],
+                                },
+                            },
+                            multiSelect: { type: "boolean", description: "Whether the user may pick more than one option." },
+                        },
+                        required: ["question", "options"],
+                    },
+                },
             },
-            required: ["question", "options"],
+            required: ["questions"],
+        },
+        summarizeArgs(args) {
+            const { questions, error } = parseQuestions(args);
+            if (error)
+                return "invalid";
+            return `${questions.length} question${questions.length === 1 ? "" : "s"}`;
         },
         async execute(args, _ctx) {
-            const question = args.question;
-            const options = Array.isArray(args.options) ? args.options : [];
-            if (!options.length) {
-                return toolError("options must contain at least one choice");
-            }
-            return { content: await ask(question, options) };
+            const { questions, error } = parseQuestions(args);
+            if (error)
+                return toolError(error);
+            const answers = await ask(questions);
+            const result = {};
+            questions.forEach((q, i) => {
+                result[q.question] = answers[i] ?? "";
+            });
+            return { content: JSON.stringify(result) };
         },
-        argSummaryKeys: ["question"],
     };
 }

package/dist/tools/registry.d.ts

@@ -1,4 +1,5 @@
 import type { Tool, ToolContext, ToolSchema, Todo } from "./types.js";
+import { type AskAnswer, type AskQuestion } from "./ask-user.js";
 import { type SubAgentToolDeps } from "./sub-agent.js";
 import type { Skill } from "../skills/types.js";
 import type { TextResult } from "./types.js";
@@ -22,7 +23,7 @@ export interface BuiltinToolsOptions {
     subAgent?: boolean;
 }
 export interface BuiltinToolsDeps {
-    ask: (question: string, options: string[]) => Promise<string>;
+    ask: (questions: AskQuestion[]) => Promise<AskAnswer[]>;
     setTodos: (todos: Todo[]) => void;
     resolveSkill?: (name: string) => Skill | undefined;
     subAgent: SubAgentToolDeps;

package/dist/tools/sub-agent.d.ts

@@ -1,6 +1,6 @@
 import type { SubAgentRunResult } from "../runtime/sub-agent-runner.js";
 import type { Tool } from "./types.js";
-export declare const SUB_AGENT_GUIDANCE = "- Consider delegating to the SubAgent tool when the task matches an agent type, when you have independent work to run in parallel, or when answering would mean reading across several files \u2014 delegate and keep the conclusion, not the file dumps. type: \"explore\" \u2014 read-only search agent for broad fan-out searches (state the search breadth in the task); type: \"plan\" \u2014 software architect producing implementation plans. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you have delegated a search, do not also run it yourself \u2014 wait for the result. Issue at most 2 SubAgent calls per turn; multiple calls in the same turn run concurrently. Sub-agents are read-only and return only their final report, not intermediate steps \u2014 verify important results yourself. For large workloads with many independent items that would exceed the turn budget, split the items into chunks sized so each sub-agent can complete its chunk within its own loop budget, delegate one SubAgent per chunk, and run the remaining chunks in the following turns as results return. Instruct each sub-agent to report results per item in structured lines so you can consolidate.";
+export declare const SUB_AGENT_GUIDANCE = "- Consider delegating to the SubAgent tool when the task matches an agent type, when you have independent work to run in parallel, or when answering would mean reading across several files \u2014 delegate and keep the conclusion, not the file dumps. The only valid values for type are \"explore\" \u2014 read-only search agent for broad fan-out searches (state the search breadth in the task) \u2014 and \"plan\" \u2014 software architect producing implementation plans; never use any other value. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you have delegated a search, do not also run it yourself \u2014 wait for the result. Issue at most 2 SubAgent calls per turn; multiple calls in the same turn run concurrently. Sub-agents are read-only and return only their final report, not intermediate steps \u2014 verify important results yourself. For large workloads with many independent items that would exceed the turn budget, split the items into chunks sized so each sub-agent can complete its chunk within its own loop budget, delegate one SubAgent per chunk, and run the remaining chunks in the following turns as results return. Instruct each sub-agent to report results per item in structured lines so you can consolidate.";
 export interface SubAgentToolDeps {
     runSubAgent: (systemPrompt: string, task: string, signal?: AbortSignal) => Promise<SubAgentRunResult>;
 }

package/dist/tools/sub-agent.js

@@ -2,7 +2,7 @@ import { NOT_EXECUTED_PREFIX } from "../util/constants.js";
 import { summarizeText } from "../util/text.js";
 import { toolError } from "./types.js";
 const MAX_LABEL_LENGTH = 50;
-export const SUB_AGENT_GUIDANCE = '- Consider delegating to the SubAgent tool when the task matches an agent type, when you have independent work to run in parallel, or when answering would mean reading across several files — delegate and keep the conclusion, not the file dumps. type: "explore" — read-only search agent for broad fan-out searches (state the search breadth in the task); type: "plan" — software architect producing implementation plans. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you have delegated a search, do not also run it yourself — wait for the result. Issue at most 2 SubAgent calls per turn; multiple calls in the same turn run concurrently. Sub-agents are read-only and return only their final report, not intermediate steps — verify important results yourself. For large workloads with many independent items that would exceed the turn budget, split the items into chunks sized so each sub-agent can complete its chunk within its own loop budget, delegate one SubAgent per chunk, and run the remaining chunks in the following turns as results return. Instruct each sub-agent to report results per item in structured lines so you can consolidate.';
+export const SUB_AGENT_GUIDANCE = '- Consider delegating to the SubAgent tool when the task matches an agent type, when you have independent work to run in parallel, or when answering would mean reading across several files — delegate and keep the conclusion, not the file dumps. The only valid values for type are "explore" — read-only search agent for broad fan-out searches (state the search breadth in the task) — and "plan" — software architect producing implementation plans; never use any other value. For a single-fact lookup where you already know the file, symbol, or value, search directly. Once you have delegated a search, do not also run it yourself — wait for the result. Issue at most 2 SubAgent calls per turn; multiple calls in the same turn run concurrently. Sub-agents are read-only and return only their final report, not intermediate steps — verify important results yourself. For large workloads with many independent items that would exceed the turn budget, split the items into chunks sized so each sub-agent can complete its chunk within its own loop budget, delegate one SubAgent per chunk, and run the remaining chunks in the following turns as results return. Instruct each sub-agent to report results per item in structured lines so you can consolidate.';
 const EXPLORE_PROMPT = [
     "You are the Explore sub-agent — a read-only search agent for broad fan-out searches. Use it when answering means sweeping many files, directories, or naming conventions and the parent needs only the conclusion, not the file dumps. You read excerpts rather than whole files, so you locate code — you do not review or audit it. You are read-only: you must not modify any files.",
     "Guidelines:",
@@ -40,7 +40,7 @@ const SUB_AGENT_DEFS = [
         systemPrompt: PLAN_PROMPT,
     },
 ];
-const TOOL_DESCRIPTION = 'Run a dedicated sub-agent in its own nested loop — the only result you receive is its final report as text, not intermediate steps. type: "explore" — a read-only search agent for broad fan-out searches of the codebase or web; specify a search breadth in the task ("medium" for moderate exploration, "very thorough" for multiple locations and naming conventions). type: "plan" — a software architect that reads the relevant code first, then returns a step-by-step implementation plan identifying critical files and architectural trade-offs. Sub-agents are read-only and cannot ask questions, use skills, or spawn further sub-agents.';
+const TOOL_DESCRIPTION = 'Run a dedicated sub-agent in its own nested loop — the only result you receive is its final report as text, not intermediate steps. type: "explore" — a read-only search agent for broad fan-out searches of the codebase or web; specify a search breadth in the task ("medium" for moderate exploration, "very thorough" for multiple locations and naming conventions). type: "plan" — a software architect that reads the relevant code first, then returns a step-by-step implementation plan identifying critical files and architectural trade-offs. These are the only two valid type values — never pass any other string. Sub-agents are read-only and cannot ask questions, use skills, or spawn further sub-agents.';
 export function createSubAgentTool(deps) {
     return {
         name: "SubAgent",
@@ -51,7 +51,7 @@ export function createSubAgentTool(deps) {
                 type: {
                     type: "string",
                     enum: SUB_AGENT_DEFS.map((d) => d.type),
-                    description: 'The sub-agent type to invoke: "explore" (read-only fan-out search) or "plan" (implementation plan).',
+                    description: 'The sub-agent type to invoke — only "explore" (read-only fan-out search) or "plan" (implementation plan) is valid.',
                 },
                 label: {
                     type: "string",

package/dist/util/constants.d.ts

@@ -14,7 +14,7 @@ export declare const DEFAULT_STALL_THRESHOLD = 3;
 export declare const DEFAULT_MAX_TURNS = 50;
 export declare const DEFAULT_FILE_READ_LIMIT = 2000;
 export declare const DEFAULT_GREP_LIMIT = 200;
-export declare const MAX_PARALLEL_TOOL_CALLS = 8;
+export declare const DEFAULT_MAX_PARALLEL_TOOL_CALLS = 10;
 export declare const SKILL_TOOL_NAME: "Skill";
 export declare const LLM_MAX_RETRIES = 3;
 export declare const WEB_FETCH_RETRIES = 2;

package/dist/util/constants.js

@@ -14,7 +14,7 @@ export const DEFAULT_STALL_THRESHOLD = 3;
 export const DEFAULT_MAX_TURNS = 50;
 export const DEFAULT_FILE_READ_LIMIT = 2000;
 export const DEFAULT_GREP_LIMIT = 200;
-export const MAX_PARALLEL_TOOL_CALLS = 8;
+export const DEFAULT_MAX_PARALLEL_TOOL_CALLS = 10;
 export const SKILL_TOOL_NAME = "Skill";
 export const LLM_MAX_RETRIES = 3;
 export const WEB_FETCH_RETRIES = 2;

package/dist/util/net.js

@@ -15,8 +15,11 @@ const undiciFetch = fetch;
 export async function netFetch(input, init) {
     if (!proxyInitialized)
         ensureProxy();
+    const headers = new Headers(init?.headers);
+    if (!headers.has("accept-encoding"))
+        headers.set("accept-encoding", "gzip, deflate");
     if (!proxyAgent)
-        return undiciFetch(input, init);
+        return undiciFetch(input, { ...init, headers });
     const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
     if (noProxyList) {
         const hostname = new URL(url).hostname;
@@ -26,7 +29,7 @@ export async function netFetch(input, init) {
             return hostname === p || hostname.endsWith("." + p);
         });
         if (shouldBypass)
-            return undiciFetch(input, init);
+            return undiciFetch(input, { ...init, headers });
     }
-    return undiciFetch(input, { ...init, dispatcher: proxyAgent });
+    return undiciFetch(input, { ...init, headers, dispatcher: proxyAgent });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vietor/agent-core",
-  "version": "0.7.6",
+  "version": "0.8.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",