anyclaude-sdk 0.2.0 → 0.4.0

package/README.md

@@ -1,9 +1,13 @@
 # anyclaude-sdk
 
-Claude Code agent capabilities — tools, the tool loop, multi-turn conversations —
-running **entirely in the browser** via [WebContainer](https://webcontainers.io),
-against **any OpenAI- or Anthropic-compatible LLM endpoint**. No backend, no OAuth,
-no native binaries.
+Claude Code agent capabilities — tools, the tool loop, multi-turn conversations,
+MCP, sub-agents, sessions — against **any OpenAI- or Anthropic-compatible LLM
+endpoint**, running in the **browser** ([WebContainer](https://webcontainers.io)),
+**Node**, and **Bun**. No backend required, no OAuth, no native binaries.
+
+> **Live demo:** [a full IDE running in your browser](https://anyclaude-docs.puter.site/demo/) ·
+> **Docs:** [anyclaude-docs.puter.site](https://anyclaude-docs.puter.site) ·
+> **React UI kit:** [`anyclaude-react`](anyclaude-react/)
 
 It exposes the same `query()` async-generator interface and the same `SDKMessage`
 envelope as `@anthropic-ai/claude-agent-sdk`, so code written against the official
@@ -267,18 +271,75 @@ await fs.writeFile('/app/index.ts', 'export const x = 1')
 const workspace = composeWorkspace(fs, new NoopCommandExecutor())
 ```
 
+## Serverless & the "survivor"
+
+Run `query()` in a serverless function and stream `SDKMessage`s to the browser. For runs longer than the platform's time cap, checkpoint at a turn boundary and continue transparently in a fresh invocation:
+
+```ts
+// pause near the deadline, persist to the store, emit a `paused` message
+query({ prompt, workspace, llm, sessionStore, maxDurationMs: 20_000 })
+// later — resume + continue the tool loop with NO new user message
+query({ workspace, llm, sessionStore, resume: true, continueRun: true })
+```
+
+Pluggable `SessionStore` adapters (all implement `SessionStoreLike`): `SessionStore` (IndexedDB), `MemorySessionStore`, `KVSessionStore` (Vercel KV / Upstash), `RedisSessionStore`, `PostgresSessionStore` (Neon / pg / postgres.js), `SupabaseSessionStore`.
+
+## Client-side tools — server brain, browser hands
+
+Declare tools the **host** executes — e.g. run `bash` in the user's browser WebContainer while the agent loop runs on your server. The run pauses with a `client_tool_request`; the client executes it and you resume with the result:
+
+```ts
+query({ prompt, llm, workspace, sessionId, clientTools: ['bash'] })   // → emits client_tool_request + pauses
+query({ llm, workspace, sessionId, resume: true, continueRun: true, clientToolResults })  // → continues
+```
+
+## Interactive — `ask_user_question`
+
+Provide `onAskUser` and the agent gains an `ask_user_question` tool to put a multiple-choice decision to the user:
+
+```ts
+query({ prompt, workspace, llm, onAskUser: async ({ question, options }) => pickOne(question, options) })
+```
+
+## Hiding your prompt from the browser (projection)
+
+The agent loop runs server-side, so your system prompt, tool instructions, and retrieved context live in the server→LLM request and **never reach the browser**. To also strip sensitive artifacts (reasoning, raw tool output / RAG, model identity) from the streamed messages, wrap the stream — a pure, opt-in output transform:
+
+```ts
+import { projectMessages } from 'anyclaude-sdk'
+for await (const m of projectMessages(query({ /* ... */ }), { preset: 'public' }))
+  res.write(JSON.stringify(m) + '\n')
+```
+
+`paused` and `client_tool_request` control messages are always preserved. (Note: anything that *runs in the browser* — `createAgentClient` mode — necessarily exposes its request; use the server/endpoint path when the prompt is proprietary.)
+
+## React UI kit — `anyclaude-react`
+
+```bash
+npm install anyclaude-react
+```
+
+`useAgent()` plus restylable components — chat (`AgentChat`, `ChatPanel`, `Transcript`, `MarkdownMessage`, `Composer`, `Working`, `ToolCall`) and an IDE set (`Terminal`, `FileExplorer`, `CodeEditor`, `AskUser`). `createAgentClient` / `createEndpointClient` auto-stitch `paused` continuations and run `clientTools` in the browser.
+
+## Examples & live demo
+
+Runnable Vite projects in [`examples/`](examples/): **`browser-ide`** (WebContainer IDE — real shell + Node in the tab), `browser-chat`, `vercel-kv-survivor`, `vercel-supabase-survivor`, `vercel-indexeddb-survivor`, **`vercel-clienttools`** (server brain / browser hands). Try the **[live demo](https://anyclaude-docs.puter.site/demo/)**.
+
 ## API
 
 - `query(options): AsyncGenerator<SDKMessage>` — main entry.
   - `prompt: string | AsyncIterable<SDKUserMessage>`
   - `workspace: FileSystem & CommandExecutor`
   - `llm: LLMClient`
-  - `tools?`, `model?`, `systemPrompt?`, `maxTurns?` (default 50), `cwd?`, `abortController?`
-- `createOpenAIClient(options): LLMClient`
-- `createAnthropicClient(options): LLMClient`
-- `WebContainerWorkspace`, `MemoryFileSystem`, `NoopCommandExecutor`
+  - `tools?`, `extraTools?`, `allowedTools?`/`disallowedTools?`, `model?`, `systemPrompt?`/`appendSystemPrompt?`, `maxTurns?` (default 50), `cwd?`, `abortController?`
+  - serverless: `sessionStore?`, `resume?`, `maxDurationMs?`, `continueRun?`
+  - client tools: `clientTools?`, `clientToolResults?`; interactive: `onAskUser?`
+  - also: `mcpServers?`, `agents?`, `commands?`, `hooks?`, `background?`, `team?`, `memory?`, `permissionMode?`/`canUseTool?`, `messageQueue?`
+- `createOpenAIClient` / `createAnthropicClient` / `createResponsesClient`
+- `WebContainerWorkspace`, `MemoryFileSystem`, `NoopCommandExecutor`, `LocalSandbox`, `composeWorkspace`
+- `defineTool` (custom tools), `projectMessages` (server-side stream redaction)
 - `ALL_CLAUDE_CODE_TOOLS`, individual tools, `toolDefs`, `toolByName`
-- All `SDK*` message types, `ContentBlockParam`, `LLMClient`, `ToolDef`, etc.
+- All `SDK*` message types, `ContentBlockParam`, `LLMClient`, `ToolDef`, `SessionStoreLike`, etc.
 
 ## Differences from the official SDK
 
@@ -286,9 +347,11 @@ const workspace = composeWorkspace(fs, new NoopCommandExecutor())
 |---------|-------------|--------------------|
 | Auth | OAuth token | None required |
 | Backend | claude.ai API | Any OpenAI/Anthropic endpoint |
-| File ops | Native filesystem | WebContainer fs (pluggable) |
-| Commands | Native shell | jsh (WebContainer) |
-| MCP / slash commands / background tasks | Built-in | Not included |
+| Runtime | Node only | Browser, Node, Bun |
+| File ops | Native filesystem | Pluggable (WebContainer / Memory / IndexedDB / local) |
+| Commands | Native shell | jsh (WebContainer) / local / client-side tools |
+| MCP / slash commands / background tasks / sub-agents | Built-in | Built-in |
+| Serverless survivor + prompt projection | — | Built-in |
 
 ## License
 

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

@@ -13,6 +13,7 @@ export * from './mcp/index.js';
 export * from './commands/index.js';
 export * from './background/index.js';
 export * from './queue.js';
+export { projectMessages, projectMessage, type ProjectionOptions, type ProjectionPreset, } from './projection.js';
 export * from './team/index.js';
 export * from './session/index.js';
 export * from './memory/index.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export * from './mcp/index.js';
 export * from './commands/index.js';
 export * from './background/index.js';
 export * from './queue.js';
+export { projectMessages, projectMessage, } from './projection.js';
 export * from './team/index.js';
 export * from './session/index.js';
 export * from './memory/index.js';

package/dist/projection.d.ts

@@ -0,0 +1,29 @@
+import type { SDKMessage } from './types/index.js';
+export type ProjectionPreset = 'public' | 'raw';
+export interface ProjectionOptions {
+    /** 'public' (browser-safe defaults) or 'raw' (passthrough; only explicit opts apply). Default 'public'. */
+    preset?: ProjectionPreset;
+    /** Replace tool_result block content with a placeholder — hides raw tool output + RAG context. */
+    redactToolResults?: boolean;
+    /** Drop synthetic tool_result messages entirely instead of redacting their content. */
+    dropToolResults?: boolean;
+    /** Remove thinking/reasoning blocks and deltas. */
+    stripReasoning?: boolean;
+    /** Remove tool_use input args (tool NAMES still appear via usage). */
+    stripToolInput?: boolean;
+    /** Remove model/provider-identifying fields (model name, tool list, mcp servers, modelUsage). */
+    stripModelInfo?: boolean;
+    /** Placeholder substituted for redacted content. Default '[redacted]'. */
+    placeholder?: string;
+    /** Drop any message whose `type` or `subtype` is in this list. */
+    drop?: string[];
+    /** Custom transform applied last; return null to drop the message. */
+    redact?: (m: SDKMessage) => SDKMessage | null;
+}
+/** Project one message. Returns null to drop it. */
+export declare function projectMessage(msg: SDKMessage, options?: ProjectionOptions): SDKMessage | null;
+/**
+ * Wrap an SDKMessage stream, projecting each message for browser delivery.
+ * Pure output transform — does NOT affect the agent loop. Opt-in.
+ */
+export declare function projectMessages(source: AsyncIterable<SDKMessage>, options?: ProjectionOptions): AsyncGenerator<SDKMessage>;

package/dist/projection.js

@@ -0,0 +1,99 @@
+function resolve(o) {
+    const pub = (o.preset ?? 'public') === 'public';
+    return {
+        redactToolResults: o.redactToolResults ?? pub,
+        dropToolResults: o.dropToolResults ?? false,
+        stripReasoning: o.stripReasoning ?? pub,
+        stripToolInput: o.stripToolInput ?? false,
+        stripModelInfo: o.stripModelInfo ?? pub,
+        placeholder: o.placeholder ?? '[redacted]',
+        drop: o.drop ?? [],
+        redact: o.redact,
+    };
+}
+/** Project one message. Returns null to drop it. */
+export function projectMessage(msg, options = {}) {
+    const o = resolve(options);
+    const m = msg;
+    const type = m.type;
+    const subtype = m.subtype;
+    if (o.drop.includes(type) || (subtype && o.drop.includes(subtype)))
+        return null;
+    // Control messages the client must act on — never alter (survivor + client tools).
+    if (type === 'system' && (subtype === 'paused' || subtype === 'client_tool_request')) {
+        return o.redact ? o.redact(msg) : msg;
+    }
+    let out = msg;
+    if (type === 'user') {
+        // Synthetic tool_result messages carry raw tool output + retrieved context.
+        const message = m.message;
+        const content = message?.content;
+        if (Array.isArray(content) && content.some((b) => b.type === 'tool_result')) {
+            if (o.dropToolResults)
+                return o.redact ? o.redact(msg) ?? null : null;
+            if (o.redactToolResults) {
+                const newContent = content.map((b) => b.type === 'tool_result' ? { ...b, content: o.placeholder } : b);
+                out = { ...m, message: { ...message, content: newContent } };
+            }
+        }
+    }
+    else if (type === 'assistant') {
+        const message = m.message;
+        let content = message.content;
+        if (o.stripReasoning)
+            content = content.filter((b) => b.type !== 'thinking');
+        if (o.stripToolInput)
+            content = content.map((b) => (b.type === 'tool_use' ? { ...b, input: {} } : b));
+        const newMessage = { ...message, content };
+        if (o.stripModelInfo)
+            newMessage.model = '';
+        out = { ...m, message: newMessage };
+    }
+    else if (type === 'stream_event') {
+        const event = m.event;
+        const et = event?.type;
+        if (o.stripReasoning) {
+            if (et === 'content_block_delta' && event.delta?.type === 'thinking_delta')
+                return null;
+            if (et === 'content_block_start' && event.content_block?.type === 'thinking')
+                return null;
+        }
+        if (o.stripModelInfo && et === 'message_start') {
+            const sm = { ...event.message };
+            delete sm.model;
+            out = { ...m, event: { ...event, message: sm } };
+        }
+    }
+    else if (type === 'system' && subtype === 'init') {
+        if (o.stripModelInfo) {
+            out = {
+                ...m,
+                model: '',
+                tools: [],
+                mcp_servers: [],
+                slash_commands: [],
+                skills: [],
+                agents: [],
+                apiKeySource: 'none',
+                cwd: '',
+            };
+        }
+    }
+    else if (type === 'result') {
+        if (o.stripModelInfo) {
+            out = { ...m, modelUsage: {} };
+        }
+    }
+    return o.redact ? o.redact(out) : out;
+}
+/**
+ * Wrap an SDKMessage stream, projecting each message for browser delivery.
+ * Pure output transform — does NOT affect the agent loop. Opt-in.
+ */
+export async function* projectMessages(source, options = {}) {
+    for await (const m of source) {
+        const out = projectMessage(m, options);
+        if (out)
+            yield out;
+    }
+}

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.4.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",