@vietor/agent-core 0.7.5 → 0.8.0

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/glob.js

@@ -1,6 +1,6 @@
 import { formatRipgrepOutput, ripgrepResultSummary, runRipgrepLines } from "../util/ripgrep.js";
 import { NO_MATCHES } from "../util/constants.js";
-import { resolveOptionalPath } from "../util/file.js";
+import { resolveSearchPath } from "../util/file.js";
 const DESCRIPTION = "List files under a directory, optionally filtered by a glob pattern (e.g. **/*.ts). Skips node_modules and .git.";
 export const globTool = {
     name: "Glob",
@@ -15,12 +15,12 @@ export const globTool = {
         required: [],
     },
     async execute(args, ctx) {
-        const cwd = resolveOptionalPath(args, ctx.cwd);
+        const { cwd, target } = resolveSearchPath(args, ctx.cwd);
         const rgArgs = ["--files"];
         const pattern = args.pattern;
         if (pattern)
             rgArgs.push("-g", pattern);
-        rgArgs.push(".");
+        rgArgs.push(target);
         const { lines, truncated } = await runRipgrepLines(rgArgs, cwd, ctx.signal);
         return { content: formatRipgrepOutput(lines, truncated, NO_MATCHES) };
     },

package/dist/tools/grep.js

@@ -1,6 +1,6 @@
 import { formatRipgrepOutput, ripgrepResultSummary, runRipgrepLines } from "../util/ripgrep.js";
 import { DEFAULT_GREP_LIMIT, NO_MATCHES } from "../util/constants.js";
-import { resolveOptionalPath } from "../util/file.js";
+import { resolveSearchPath } from "../util/file.js";
 const DESCRIPTION = `Search file contents recursively for a regex pattern (RE2 syntax). Skips node_modules and .git. Returns path:line:content, capped at ${DEFAULT_GREP_LIMIT} lines. For large codebases, use output_mode=files_with_matches first, or narrow with glob/type, or raise head_limit.`;
 export const grepTool = {
     name: "Grep",
@@ -10,7 +10,7 @@ export const grepTool = {
         type: "object",
         properties: {
             pattern: { type: "string" },
-            path: { type: "string", description: "root directory, defaults to cwd" },
+            path: { type: "string", description: "file or directory, defaults to cwd" },
             glob: { type: "string", description: "filter files, e.g. *.ts" },
             type: { type: "string", description: "file type, e.g. ts, js, py" },
             output_mode: { type: "string", enum: ["content", "files_with_matches", "count"], description: "defaults to content" },
@@ -25,7 +25,7 @@ export const grepTool = {
         required: ["pattern"],
     },
     async execute(args, ctx) {
-        const cwd = resolveOptionalPath(args, ctx.cwd);
+        const { cwd, target } = resolveSearchPath(args, ctx.cwd);
         const rgArgs = ["--line-number", "--with-filename", "--no-heading"];
         if (args.ignore_case)
             rgArgs.push("-i");
@@ -56,7 +56,7 @@ export const grepTool = {
             rgArgs.push("-c");
         else
             rgArgs.push("-m", String(headLimit));
-        rgArgs.push("--", args.pattern, ".");
+        rgArgs.push("--", args.pattern, target);
         const { lines, truncated } = await runRipgrepLines(rgArgs, cwd, ctx.signal, headLimit);
         return { content: formatRipgrepOutput(lines, truncated, NO_MATCHES) };
     },

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.js

@@ -1,5 +1,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.';
 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.",
@@ -51,11 +53,21 @@ export function createSubAgentTool(deps) {
                     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).',
                 },
+                label: {
+                    type: "string",
+                    maxLength: MAX_LABEL_LENGTH,
+                    description: `Short label (max ${MAX_LABEL_LENGTH} characters) for this sub-agent run, shown in the UI.`,
+                },
                 task: { type: "string", description: "The task or question for the sub-agent, as a self-contained description." },
             },
             required: ["type", "task"],
         },
-        argSummaryKeys: ["type"],
+        summarizeArgs: (args) => {
+            const type = args.type;
+            const label = typeof args.label === "string" ? summarizeText(args.label, MAX_LABEL_LENGTH) : "";
+            const def = SUB_AGENT_DEFS.find((d) => d.type === type);
+            return (def?.name || type) + (label ? ` ${label}` : "");
+        },
         async execute(args, ctx) {
             const type = args.type;
             const task = (args.task ?? "").trim();
@@ -80,7 +92,7 @@ export function createSubAgentTool(deps) {
                 }
             }
             const suffix = stallReason ? ` ${stallReason}` : "";
-            return { content: `Sub-agent "${type}" ended with status ${status}.${suffix}\n\n${reply}`, isError: true };
+            return { content: `Sub-agent "${def.name}" ended with status ${status}.${suffix}\n\n${reply}`, isError: true };
         },
     };
 }

package/dist/util/async.js

@@ -11,7 +11,7 @@ export function isAbortError(e) {
     return name === "AbortError" || name === "APIUserAbortError";
 }
 export function backoffDelay(attempt) {
-    return 1000 * 2 ** attempt;
+    return Math.min(2000 * 2 ** attempt, 60_000);
 }
 export async function withRetry(fn, opts) {
     for (let attempt = 0;; attempt++) {

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/file.d.ts

@@ -1,3 +1,6 @@
 export declare function tryReadFileText(path: string): string | undefined;
 export declare function resolveRequiredPath(args: Record<string, unknown>, cwd: string): string;
-export declare function resolveOptionalPath(args: Record<string, unknown>, cwd: string): string;
+export declare function resolveSearchPath(args: Record<string, unknown>, cwd: string): {
+    cwd: string;
+    target: string;
+};

package/dist/util/file.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 export function tryReadFileText(path) {
     if (existsSync(path)) {
@@ -14,6 +14,10 @@ export function resolveRequiredPath(args, cwd) {
         throw new Error("path is required");
     return resolve(cwd, path);
 }
-export function resolveOptionalPath(args, cwd) {
-    return resolve(cwd, args.path || "");
+export function resolveSearchPath(args, cwd) {
+    const path = resolve(cwd, args.path || "");
+    if (existsSync(path) && !statSync(path).isDirectory()) {
+        return { cwd, target: path };
+    }
+    return { cwd: path, target: "." };
 }

package/package.json

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