anyclaude-sdk 0.2.0 → 0.3.0

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDefinition, CanUseTool, CommandExecutor, FileSystem, HookCallback, HookEvent, PermissionMode, SDKMessage, SDKUserMessage } from './types/index.js';
+import type { AgentDefinition, CanUseTool, CommandExecutor, ContentBlockParam, FileSystem, HookCallback, HookEvent, PermissionMode, SDKMessage, SDKUserMessage } from './types/index.js';
 import type { FileReadLimits, Tool } from './tools/types.js';
 import { type McpServers, type McpProxy } from './mcp/index.js';
 import type { SlashCommand } from './commands/index.js';
@@ -34,6 +34,16 @@ export interface AgentOptions {
     /** Resume + CONTINUE the tool loop on the stored transcript without a new user
      *  message (pairs with `resume`). Used to continue after a `paused` boundary. */
     continueRun?: boolean;
+    /** Tool names executed by the HOST/client, not the server. When the agent calls
+     *  one, the loop emits a `client_tool_request` + pauses; the client runs it and
+     *  resumes (continueRun) with `clientToolResults`. (e.g. bash on a browser WebContainer.) */
+    clientTools?: string[];
+    /** Results for client-tool calls, injected into the transcript before continuing. */
+    clientToolResults?: Array<{
+        tool_use_id: string;
+        content: string | ContentBlockParam[];
+        is_error?: boolean;
+    }>;
     cwd?: string;
     sessionId?: string;
     abortController?: AbortController;
@@ -102,6 +112,16 @@ export interface AgentOptions {
     };
     /** Prompt callback for 'ask' decisions; if absent, default mode allows / dontAsk denies. */
     onPermissionAsk?: (toolName: string, input: Record<string, unknown>) => Promise<boolean>;
+    /** Surfaces `ask_user_question` to the host UI. When set, the tool is registered. */
+    onAskUser?: (q: {
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect?: boolean;
+    }) => Promise<string | string[]>;
     /** Load + apply `.claude/settings.json` (project/local cascade) under explicit options. true, or a Settings object. */
     settings?: boolean | Settings;
     /** Load `.claude/skills/*.md` as slash commands + skill registry. true, or a Skill[] array. */

package/dist/agent.js

@@ -10,6 +10,7 @@
 //   7. Repeat until no tool calls or max turns reached
 import { ALL_CLAUDE_CODE_TOOLS, toolByName, toolDefs } from './tools/index.js';
 import { task as taskTool } from './tools/task.js';
+import { askUserQuestion } from './tools/ask_user.js';
 import { loadMcpServers } from './mcp/index.js';
 import { runSlashCommand } from './commands/index.js';
 import { BackgroundTaskManager, BACKGROUND_TOOLS } from './background/index.js';
@@ -201,6 +202,7 @@ export async function* runAgent(options) {
         ? options.backgroundManager ?? new BackgroundTaskManager()
         : undefined;
     const messageQueue = options.messageQueue;
+    const clientTools = new Set(options.clientTools ?? []);
     // Teammates: a shared Mailbox + TaskBoard (reused from the parent when this
     // is a sub-agent) + team tools + coordinator prompt.
     const teamEnabled = options.team === true;
@@ -214,6 +216,9 @@ export async function* runAgent(options) {
         const present = new Set(localTools.map((t) => t.def.function.name));
         localTools = [...localTools, ...BACKGROUND_TOOLS.filter((t) => !present.has(t.def.function.name))];
     }
+    if (options.onAskUser && !localTools.some((t) => t.def.function.name === 'ask_user_question')) {
+        localTools = [...localTools, askUserQuestion];
+    }
     if (teamEnabled) {
         const present = new Set(localTools.map((t) => t.def.function.name));
         const teamSet = subagentsEnabled ? [...TEAM_TOOLS, ...TEAM_DISPATCH_TOOLS] : TEAM_TOOLS;
@@ -267,6 +272,7 @@ export async function* runAgent(options) {
         signal,
         store,
         limits,
+        askUser: options.onAskUser,
         background,
         mailbox,
         board,
@@ -308,6 +314,7 @@ export async function* runAgent(options) {
                 tools: subTools,
                 model: def?.model ?? model,
                 systemPrompt: subSystem,
+                onAskUser: options.onAskUser,
                 maxTurns,
                 cwd,
                 abortController: childController,
@@ -405,6 +412,8 @@ export async function* runAgent(options) {
     const sessionUsage = emptyUsage();
     const maxDurationMs = options.maxDurationMs;
     let paused = false;
+    // Pending client-executed tool calls for the current turn (emitted on pause).
+    let clientRequests = [];
     // Resume: seed the transcript from a prior session before the first turn.
     if (options.resume && options.sessionStore) {
         const prior = await options.sessionStore.load(sessionId);
@@ -495,6 +504,28 @@ export async function* runAgent(options) {
             if (extra)
                 history.push({ role: 'user', content: extra });
         }
+        // Continue after a client-tool pause: inject the host-executed results into
+        // the transcript so the (paused) assistant tool_use calls are now resolved.
+        if (isContinue && options.clientToolResults?.length) {
+            const blocks = [];
+            for (const r of options.clientToolResults) {
+                history.push({
+                    role: 'tool',
+                    tool_call_id: r.tool_use_id,
+                    content: typeof r.content === 'string' ? r.content : JSON.stringify(r.content),
+                });
+                blocks.push({ type: 'tool_result', tool_use_id: r.tool_use_id, content: r.content, is_error: r.is_error || undefined });
+            }
+            yield {
+                type: 'user',
+                message: { role: 'user', content: blocks },
+                parent_tool_use_id: null,
+                isSynthetic: true,
+                timestamp: new Date().toISOString(),
+                uuid: uuid(),
+                session_id: sessionId,
+            };
+        }
         let turns = 0;
         let lastText = '';
         let resultModel = model ?? 'unknown';
@@ -659,12 +690,19 @@ export async function* runAgent(options) {
             }
             // Execute tool calls (permission gate + hooks around each).
             const toolResultBlocks = [];
+            clientRequests = [];
             const turnMedia = [];
             for (const call of calls) {
                 if (signal?.aborted)
                     break;
                 const name = call.function.name;
                 let input = safeParse(call.function.arguments);
+                // Client-executed tool: don't run it here — record it; we pause after this
+                // turn's server tools and let the host execute + resume with the result.
+                if (clientTools.has(name)) {
+                    clientRequests.push({ tool_use_id: call.id, name, input });
+                    continue;
+                }
                 const tool = byName.get(name);
                 let content = '';
                 let isError = false;
@@ -829,15 +867,23 @@ export async function* runAgent(options) {
                     ],
                 });
             }
-            yield {
-                type: 'user',
-                message: { role: 'user', content: toolResultBlocks },
-                parent_tool_use_id: null,
-                isSynthetic: true,
-                timestamp: new Date().toISOString(),
-                uuid: uuid(),
-                session_id: sessionId,
-            };
+            if (toolResultBlocks.length) {
+                yield {
+                    type: 'user',
+                    message: { role: 'user', content: toolResultBlocks },
+                    parent_tool_use_id: null,
+                    isSynthetic: true,
+                    timestamp: new Date().toISOString(),
+                    uuid: uuid(),
+                    session_id: sessionId,
+                };
+            }
+            // Client-executed tools were requested this turn → pause; the host runs
+            // them and resumes (continueRun + clientToolResults).
+            if (clientRequests.length) {
+                paused = true;
+                break;
+            }
         }
         await runHooks('Stop', {
             hook_event_name: 'Stop',
@@ -902,13 +948,23 @@ export async function* runAgent(options) {
                 /* persistence is best-effort */
             }
         }
-        // Survivor: hit the time budget. The transcript is persisted (above); signal
-        // the client to continue the run in a fresh invocation (resume + continueRun).
+        // Survivor / client-tools: paused at a boundary. Transcript persisted above.
+        // Emit any client-tool requests for the host to execute, then signal the
+        // client to continue in a fresh invocation (resume + continueRun [+ results]).
         if (paused) {
+            for (const req of clientRequests) {
+                yield {
+                    type: 'system',
+                    subtype: 'client_tool_request',
+                    request: req,
+                    session_id: sessionId,
+                    uuid: uuid(),
+                };
+            }
             yield {
                 type: 'system',
                 subtype: 'paused',
-                reason: 'time_budget',
+                reason: clientRequests.length ? 'client_tool' : 'time_budget',
                 session_id: sessionId,
                 uuid: uuid(),
             };

package/dist/query.d.ts

@@ -26,6 +26,15 @@ export interface QueryOptions {
     maxDurationMs?: number;
     /** Resume + continue the tool loop with no new user message (after a `paused` boundary). */
     continueRun?: boolean;
+    /** Tool names the HOST/client executes (e.g. bash on a browser WebContainer). The agent
+     *  emits a `client_tool_request` + pauses; the client runs it and resumes with results. */
+    clientTools?: string[];
+    /** Results for client-tool calls, injected before continuing (with continueRun). */
+    clientToolResults?: Array<{
+        tool_use_id: string;
+        content: string | import('./types/index.js').ContentBlockParam[];
+        is_error?: boolean;
+    }>;
     cwd?: string;
     sessionId?: string;
     abortController?: AbortController;
@@ -82,6 +91,16 @@ export interface QueryOptions {
     };
     /** Prompt callback for 'ask' permission decisions. */
     onPermissionAsk?: (toolName: string, input: Record<string, unknown>) => Promise<boolean>;
+    /** Handler for the `ask_user_question` tool. When set, the tool is registered. */
+    onAskUser?: (q: {
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect?: boolean;
+    }) => Promise<string | string[]>;
     /** Load `.claude/settings.json` (project/local cascade), or pass a Settings object. */
     settings?: boolean | import('./settings/index.js').Settings;
     /** Load `.claude/skills/*.md` as slash commands + a skill registry, or pass a Skill[]. */

package/dist/query.js

@@ -22,6 +22,8 @@ export function query(options) {
         maxTurns: options.maxTurns,
         maxDurationMs: options.maxDurationMs,
         continueRun: options.continueRun,
+        clientTools: options.clientTools,
+        clientToolResults: options.clientToolResults,
         cwd: options.cwd,
         sessionId: options.sessionId,
         abortController,
@@ -50,6 +52,7 @@ export function query(options) {
         memory: options.memory,
         permissionRules: options.permissionRules,
         onPermissionAsk: options.onPermissionAsk,
+        onAskUser: options.onAskUser,
         settings: options.settings,
         skills: options.skills,
     });

package/dist/tools/ask_user.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const askUserQuestion: Tool;

package/dist/tools/ask_user.js

@@ -0,0 +1,54 @@
+const DESCRIPTION = `Ask the user a multiple-choice question and wait for their answer. Use ONLY when you hit a decision that's genuinely the user's to make (choosing between distinct approaches, confirming ambiguous scope) and you can't resolve it from the request or sensible defaults. Provide 2-4 concrete, mutually-exclusive options. Prefer acting on a reasonable default over asking.`;
+export const askUserQuestion = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'ask_user_question',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    question: { type: 'string', description: 'The question to ask the user.' },
+                    header: { type: 'string', description: 'Very short label/chip for the question (max ~12 chars).' },
+                    options: {
+                        type: 'array',
+                        description: '2-4 options the user can choose from.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                label: { type: 'string', description: 'Concise choice text (1-5 words).' },
+                                description: { type: 'string', description: 'What this option means / its trade-off.' },
+                            },
+                            required: ['label'],
+                        },
+                    },
+                    multiSelect: { type: 'boolean', description: 'Allow selecting multiple options.' },
+                },
+                required: ['question', 'options'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        if (!ctx.askUser) {
+            return {
+                content: 'Interactive questions are unavailable in this environment. Choose the most reasonable option yourself, state the assumption, and continue.',
+                isError: true,
+            };
+        }
+        const question = String(input.question ?? '').trim();
+        const raw = Array.isArray(input.options) ? input.options : [];
+        const options = raw.map((o) => typeof o === 'string'
+            ? { label: o }
+            : { label: String(o.label ?? ''), description: o.description ? String(o.description) : undefined });
+        if (!question || !options.length)
+            return { content: 'Error: `question` and `options` are required.', isError: true };
+        const answer = await ctx.askUser({
+            question,
+            header: input.header ? String(input.header) : undefined,
+            options,
+            multiSelect: !!input.multiSelect,
+        });
+        const chosen = Array.isArray(answer) ? answer.join(', ') : String(answer);
+        return { content: `User answered "${question}" → ${chosen || '(no selection)'}` };
+    },
+};

package/dist/tools/index.d.ts

@@ -20,6 +20,7 @@ export { bash, readFile, writeFile, editFile, deleteFile, listFiles, glob, grep
 export { multiEdit, notebookEdit, todoWrite, webFetch, webSearch, toolSearch, config };
 export { walk, globToRegExp, joinPath, DEFAULT_IGNORE } from './walk.js';
 export { defineTool, type DefineToolSpec } from './define.js';
+export { askUserQuestion } from './ask_user.js';
 /** Every built-in Claude Code tool, ready to pass to `query()`. */
 export declare const ALL_CLAUDE_CODE_TOOLS: Tool[];
 /** Extract the OpenAI-shape definitions to send to the LLM. */

package/dist/tools/index.js

@@ -17,6 +17,7 @@ export { bash, readFile, writeFile, editFile, deleteFile, listFiles, glob, grep
 export { multiEdit, notebookEdit, todoWrite, webFetch, webSearch, toolSearch, config };
 export { walk, globToRegExp, joinPath, DEFAULT_IGNORE } from './walk.js';
 export { defineTool } from './define.js';
+export { askUserQuestion } from './ask_user.js';
 /** Every built-in Claude Code tool, ready to pass to `query()`. */
 export const ALL_CLAUDE_CODE_TOOLS = [
     bash,

package/dist/tools/types.d.ts

@@ -41,6 +41,16 @@ export interface ToolContext {
         text: string;
         isError?: boolean;
     }>;
+    /** Ask the user a multiple-choice question (wired from query({ onAskUser })). */
+    askUser?: (q: {
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect?: boolean;
+    }) => Promise<string | string[]>;
     /** Background task manager, present when background tasks are enabled. */
     background?: import('../background/manager.js').BackgroundTaskManager;
     /** Inter-agent mailbox, present when teammates are enabled. Shared with sub-agents. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyclaude-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Standalone, browser-compatible SDK providing Claude Code agent capabilities (tools, tool loop, multi-turn, MCP, sub-agents, sessions) against any OpenAI/Anthropic-compatible LLM endpoint. Runs in the browser (WebContainer), Node, and Bun — no backend required.",
   "type": "module",
   "main": "./dist/index.js",