anyclaude-sdk 0.1.0

package/dist/permissions/dangerous.js

@@ -0,0 +1,24 @@
+// Conservative detection of obviously-destructive shell commands. Used as a
+// last-resort backstop when no explicit allow rule matched.
+const PATTERNS = [
+    { re: /\brm\s+(-[a-z]*\s+)*-?[rf][rf]?\s+(\/|~|\/\*|\$HOME|\.\s*$|\*\s*$)/i, reason: 'recursive force-delete of a top-level/home path' },
+    { re: /\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r/i, reason: 'rm -rf' },
+    { re: /\bmkfs(\.\w+)?\b/i, reason: 'filesystem format (mkfs)' },
+    { re: /\bdd\b[^\n]*\bof=\/dev\/[sh]d/i, reason: 'dd write to a raw disk device' },
+    { re: />\s*\/dev\/[sh]d[a-z]/i, reason: 'redirect to a raw disk device' },
+    { re: /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, reason: 'fork bomb' },
+    { re: /\b(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(sh|bash|zsh)\b/i, reason: 'pipe remote script straight into a shell' },
+    { re: /\bchmod\s+-R\s+777\s+\//i, reason: 'recursive chmod 777 on root' },
+    { re: /\bgit\s+push\b[^\n]*--force[^\n]*\b(origin\s+)?(main|master)\b/i, reason: 'force-push to main/master' },
+    { re: /\bgit\s+push\b[^\n]*\b(main|master)\b[^\n]*--force/i, reason: 'force-push to main/master' },
+    { re: /\b(shutdown|reboot|halt|poweroff)\b/i, reason: 'system power command' },
+    { re: /\bsudo\s+rm\b/i, reason: 'sudo rm' },
+];
+export function isDangerousBash(command) {
+    const cmd = (command || '').trim();
+    for (const { re, reason } of PATTERNS) {
+        if (re.test(cmd))
+            return { dangerous: true, reason };
+    }
+    return { dangerous: false };
+}

package/dist/permissions/gate.d.ts

@@ -0,0 +1,21 @@
+import type { CanUseTool, PermissionMode } from '../types/index.js';
+import type { PermissionRuleSet, PermissionUpdateInput } from './types.js';
+export interface GateOptions {
+    /** Permission mode; 'bypassPermissions' allows all, 'plan' denies non-read-only tools. */
+    mode?: PermissionMode;
+    /** Interactive prompt for 'ask'/unmatched calls. true → allow, false → deny. */
+    onAsk?: (toolName: string, input: Record<string, unknown>) => Promise<boolean>;
+    /** Block obviously-destructive bash unless an explicit allow rule matched. Default true. */
+    flagDangerous?: boolean;
+}
+/**
+ * Build a CanUseTool from a rule set.
+ *
+ * Resolution order: bypass → plan-mode read-only check → deny rule → allow rule
+ * → dangerous-bash backstop → ask (onAsk / mode). With no UI and mode 'default'
+ * an unmatched call is ALLOWED (documented); use 'dontAsk' to deny-by-default,
+ * or provide `onAsk`.
+ */
+export declare function rulesToCanUseTool(ruleset: PermissionRuleSet, opts?: GateOptions): CanUseTool;
+/** Apply a permission update to a rule set (pure; setMode is a no-op on rules). */
+export declare function applyPermissionUpdate(ruleset: PermissionRuleSet, update: PermissionUpdateInput): PermissionRuleSet;

package/dist/permissions/gate.js

@@ -0,0 +1,66 @@
+// Turn a rule set into a CanUseTool gate, and apply permission updates.
+import { canonical, evaluate } from './match.js';
+import { isDangerousBash } from './dangerous.js';
+import { isReadOnlyTool } from './planMode.js';
+/**
+ * Build a CanUseTool from a rule set.
+ *
+ * Resolution order: bypass → plan-mode read-only check → deny rule → allow rule
+ * → dangerous-bash backstop → ask (onAsk / mode). With no UI and mode 'default'
+ * an unmatched call is ALLOWED (documented); use 'dontAsk' to deny-by-default,
+ * or provide `onAsk`.
+ */
+export function rulesToCanUseTool(ruleset, opts = {}) {
+    const flagDangerous = opts.flagDangerous !== false;
+    return async (toolName, input) => {
+        const behavior = evaluate(ruleset, toolName, input);
+        // Explicit deny is a hard block — it wins even in bypassPermissions mode.
+        if (behavior === 'deny') {
+            return { behavior: 'deny', message: `Denied by permission rule for "${toolName}".` };
+        }
+        if (opts.mode === 'bypassPermissions')
+            return { behavior: 'allow' };
+        // Plan mode: only read-only tools may run.
+        if (opts.mode === 'plan' && !isReadOnlyTool(toolName, input)) {
+            return { behavior: 'deny', message: `Plan mode: "${toolName}" is not a read-only tool; planning only.` };
+        }
+        if (behavior === 'allow')
+            return { behavior: 'allow' };
+        // Dangerous-bash backstop (only when not explicitly allowed above).
+        if (flagDangerous && canonical(toolName) === 'bash') {
+            const d = isDangerousBash(String(input.command ?? ''));
+            if (d.dangerous) {
+                return { behavior: 'deny', message: `Blocked potentially destructive command (${d.reason}). Add an allow rule to override.` };
+            }
+        }
+        // 'ask' rule or no match.
+        if (opts.onAsk) {
+            const ok = await opts.onAsk(toolName, input);
+            return ok ? { behavior: 'allow' } : { behavior: 'deny', message: 'Denied by user.' };
+        }
+        if (opts.mode === 'dontAsk') {
+            return { behavior: 'deny', message: `No matching allow rule for "${toolName}" (dontAsk mode).` };
+        }
+        return { behavior: 'allow' }; // default: no UI available → allow
+    };
+}
+/** Apply a permission update to a rule set (pure; setMode is a no-op on rules). */
+export function applyPermissionUpdate(ruleset, update) {
+    const next = {
+        allow: [...ruleset.allow],
+        deny: [...ruleset.deny],
+        ask: [...ruleset.ask],
+    };
+    const beh = update.behavior;
+    const rules = update.rules ?? [];
+    if (!beh)
+        return next;
+    if (update.type === 'addRules')
+        next[beh] = [...next[beh], ...rules];
+    else if (update.type === 'replaceRules')
+        next[beh] = [...rules];
+    else if (update.type === 'removeRules') {
+        next[beh] = next[beh].filter((r) => !rules.some((x) => x.toolName === r.toolName && x.ruleContent === r.ruleContent));
+    }
+    return next;
+}

package/dist/permissions/index.d.ts

@@ -0,0 +1,5 @@
+export type { PermissionBehavior, PermissionRule, PermissionRuleSet, PermissionUpdateInput, } from './types.js';
+export { canonical, parseRule, ruleContentForInput, matchContent, matchRule, evaluate, ruleSetFromStrings, } from './match.js';
+export { isDangerousBash } from './dangerous.js';
+export { READ_ONLY_TOOLS, isReadOnlyTool } from './planMode.js';
+export { rulesToCanUseTool, applyPermissionUpdate, type GateOptions } from './gate.js';

package/dist/permissions/index.js

@@ -0,0 +1,6 @@
+// Permission rule-matching system: allow/deny/ask rules, dangerous-command
+// detection, and plan-mode tool classification.
+export { canonical, parseRule, ruleContentForInput, matchContent, matchRule, evaluate, ruleSetFromStrings, } from './match.js';
+export { isDangerousBash } from './dangerous.js';
+export { READ_ONLY_TOOLS, isReadOnlyTool } from './planMode.js';
+export { rulesToCanUseTool, applyPermissionUpdate } from './gate.js';

package/dist/permissions/match.d.ts

@@ -0,0 +1,19 @@
+import type { PermissionBehavior, PermissionRule, PermissionRuleSet } from './types.js';
+/** Canonicalize a tool/rule name so PascalCase rules match snake_case tools. */
+export declare function canonical(name: string): string;
+/** Parse a rule string like `Bash(rm *)` or `write_file` into a PermissionRule. */
+export declare function parseRule(s: string): PermissionRule;
+/** The string a rule's content matches against, by tool. */
+export declare function ruleContentForInput(toolName: string, input: Record<string, unknown>): string | undefined;
+/** Glob/prefix match for rule content (`*`/`**` = any; bare strings prefix-match commands). */
+export declare function matchContent(pattern: string | undefined, value: string | undefined): boolean;
+/** Does a rule match this tool call? */
+export declare function matchRule(rule: PermissionRule, toolName: string, input: Record<string, unknown>): boolean;
+/** Evaluate a ruleset: deny wins, then allow, then ask; undefined if no match. */
+export declare function evaluate(ruleset: PermissionRuleSet, toolName: string, input: Record<string, unknown>): PermissionBehavior | undefined;
+/** Build a PermissionRuleSet from string-rule arrays. */
+export declare function ruleSetFromStrings(input: {
+    allow?: string[];
+    deny?: string[];
+    ask?: string[];
+}): PermissionRuleSet;

package/dist/permissions/match.js

@@ -0,0 +1,104 @@
+// Rule parsing + matching. Rules use names like "Bash(rm *)" or "write_file";
+// we canonicalize tool names (Claude Code PascalCase ↔ our snake_case) and
+// glob/prefix-match the rule content against the relevant input field.
+// Map common rule/tool name variants → our canonical snake_case tool name.
+const ALIAS = {
+    bash: 'bash', shell: 'bash', sh: 'bash', powershell: 'bash',
+    edit: 'edit_file', editfile: 'edit_file',
+    multiedit: 'multi_edit',
+    write: 'write_file', writefile: 'write_file',
+    read: 'read_file', readfile: 'read_file',
+    glob: 'glob', grep: 'grep',
+    ls: 'list_files', list: 'list_files', listfiles: 'list_files',
+    notebookedit: 'notebook_edit',
+    todowrite: 'todo_write', todo: 'todo_write',
+    webfetch: 'web_fetch', fetch: 'web_fetch',
+    websearch: 'web_search', search: 'web_search',
+    toolsearch: 'tool_search',
+    config: 'config', task: 'task', agent: 'task',
+    delete: 'delete_file', deletefile: 'delete_file',
+};
+/** Canonicalize a tool/rule name so PascalCase rules match snake_case tools. */
+export function canonical(name) {
+    const lower = name.toLowerCase().trim();
+    if (lower.startsWith('mcp__'))
+        return lower; // MCP tools match exactly
+    const key = lower.replace(/[\s_-]+/g, '');
+    return ALIAS[key] ?? lower.replace(/[\s-]+/g, '_');
+}
+/** Parse a rule string like `Bash(rm *)` or `write_file` into a PermissionRule. */
+export function parseRule(s) {
+    const m = s.match(/^\s*([^()]+?)\s*\(([\s\S]*)\)\s*$/);
+    if (m)
+        return { toolName: m[1].trim(), ruleContent: m[2].trim() };
+    return { toolName: s.trim() };
+}
+/** The string a rule's content matches against, by tool. */
+export function ruleContentForInput(toolName, input) {
+    const t = canonical(toolName);
+    if (t === 'bash')
+        return typeof input.command === 'string' ? input.command : undefined;
+    if (['read_file', 'write_file', 'edit_file', 'multi_edit', 'delete_file', 'notebook_edit', 'list_files', 'glob'].includes(t)) {
+        if (typeof input.path === 'string')
+            return input.path;
+        if (typeof input.pattern === 'string')
+            return input.pattern;
+        return undefined;
+    }
+    if (t === 'web_fetch' || t === 'web_search') {
+        if (typeof input.url === 'string')
+            return input.url;
+        if (typeof input.query === 'string')
+            return input.query;
+        return undefined;
+    }
+    return undefined;
+}
+function escapeRegex(s) {
+    // Escape every regex special INCLUDING '*' (so glob '*' becomes '\*' which we
+    // then turn into '.*' below — without this, '*'/'**' stay as invalid quantifiers).
+    return s.replace(/[.*+^${}()|[\]\\]/g, '\\$&');
+}
+/** Glob/prefix match for rule content (`*`/`**` = any; bare strings prefix-match commands). */
+export function matchContent(pattern, value) {
+    if (!pattern)
+        return true; // no content constraint → matches any input
+    if (value == null)
+        return false;
+    if (pattern === '*' || pattern === '**')
+        return true;
+    const re = new RegExp('^' + escapeRegex(pattern).replace(/\\\*\\\*/g, '.*').replace(/\\\*/g, '.*') + '$');
+    if (re.test(value))
+        return true;
+    // Convenience: a glob-free pattern prefix-matches a command/path.
+    if (!pattern.includes('*') && (value === pattern || value.startsWith(pattern + ' ') || value.startsWith(pattern + '/'))) {
+        return true;
+    }
+    return false;
+}
+/** Does a rule match this tool call? */
+export function matchRule(rule, toolName, input) {
+    if (canonical(rule.toolName) !== canonical(toolName))
+        return false;
+    if (!rule.ruleContent)
+        return true;
+    return matchContent(rule.ruleContent, ruleContentForInput(toolName, input));
+}
+/** Evaluate a ruleset: deny wins, then allow, then ask; undefined if no match. */
+export function evaluate(ruleset, toolName, input) {
+    if (ruleset.deny.some((r) => matchRule(r, toolName, input)))
+        return 'deny';
+    if (ruleset.allow.some((r) => matchRule(r, toolName, input)))
+        return 'allow';
+    if (ruleset.ask.some((r) => matchRule(r, toolName, input)))
+        return 'ask';
+    return undefined;
+}
+/** Build a PermissionRuleSet from string-rule arrays. */
+export function ruleSetFromStrings(input) {
+    return {
+        allow: (input.allow ?? []).map(parseRule),
+        deny: (input.deny ?? []).map(parseRule),
+        ask: (input.ask ?? []).map(parseRule),
+    };
+}

package/dist/permissions/planMode.d.ts

@@ -0,0 +1,3 @@
+export declare const READ_ONLY_TOOLS: Set<string>;
+/** Is this tool call read-only (safe to run in plan mode)? */
+export declare function isReadOnlyTool(toolName: string, input?: Record<string, unknown>): boolean;

package/dist/permissions/planMode.js

@@ -0,0 +1,33 @@
+// Plan-mode tool classification: in 'plan' mode only read-only tools run.
+import { canonical } from './match.js';
+export const READ_ONLY_TOOLS = new Set([
+    'read_file', 'glob', 'grep', 'list_files',
+    'web_fetch', 'web_search', 'tool_search',
+    'task_get', 'board_list', 'memory_list',
+]);
+/** Read-only bash command prefixes (program names). */
+const READ_ONLY_BASH = [
+    'ls', 'cat', 'grep', 'rg', 'find', 'pwd', 'echo', 'head', 'tail', 'wc',
+    'which', 'whoami', 'date', 'env', 'tree', 'stat', 'file', 'du', 'df',
+];
+/** Is this tool call read-only (safe to run in plan mode)? */
+export function isReadOnlyTool(toolName, input) {
+    const t = canonical(toolName);
+    if (READ_ONLY_TOOLS.has(t))
+        return true;
+    if (t === 'config') {
+        const action = String(input?.action ?? 'get');
+        return action !== 'set';
+    }
+    if (t === 'bash') {
+        const cmd = String(input?.command ?? '').trim().toLowerCase();
+        if (!cmd)
+            return false;
+        // Read-only git subcommands.
+        if (/^git\s+(status|diff|log|show|branch|remote|config\s+--get|rev-parse)\b/.test(cmd))
+            return true;
+        const prog = cmd.split(/[\s|;&]+/)[0];
+        return READ_ONLY_BASH.includes(prog);
+    }
+    return false;
+}

package/dist/permissions/types.d.ts

@@ -0,0 +1,19 @@
+export type PermissionBehavior = 'allow' | 'deny' | 'ask';
+/** A single rule: a tool name plus an optional content matcher (glob/prefix). */
+export type PermissionRule = {
+    toolName: string;
+    ruleContent?: string;
+};
+/** Rules grouped by behavior. */
+export type PermissionRuleSet = {
+    allow: PermissionRule[];
+    deny: PermissionRule[];
+    ask: PermissionRule[];
+};
+/** A loose permission-update shape (mirrors the SDK's PermissionUpdate variants). */
+export type PermissionUpdateInput = {
+    type: 'addRules' | 'replaceRules' | 'removeRules' | 'setMode' | string;
+    rules?: PermissionRule[];
+    behavior?: PermissionBehavior;
+    mode?: string;
+};

package/dist/permissions/types.js

@@ -0,0 +1,2 @@
+// Permission rule types — allow/deny/ask rules matched against tool calls.
+export {};

package/dist/persist.d.ts

@@ -0,0 +1,15 @@
+import type { FileSystem } from './types/index.js';
+/** Default char threshold before a tool result spills to disk (Claude Code uses 50k). */
+export declare const DEFAULT_MAX_RESULT_CHARS = 50000;
+/** Bytes of the full output shown inline as a preview. */
+export declare const PREVIEW_CHARS = 2000;
+/** Directory (relative to cwd) where spilled tool outputs are stored. */
+export declare const TOOL_RESULTS_DIR = ".bcs/tool-results";
+export declare const PERSISTED_OUTPUT_TAG = "<persisted-output>";
+export declare const PERSISTED_OUTPUT_CLOSING_TAG = "</persisted-output>";
+/**
+ * If `content` exceeds `threshold`, write it to a file under the workspace and
+ * return a preview message pointing the model at the path. Otherwise returns
+ * the content unchanged. Failures fall back to returning the original content.
+ */
+export declare function maybePersistLargeResult(content: string, toolUseId: string, fs: FileSystem, cwd: string, threshold?: number): Promise<string>;

package/dist/persist.js

@@ -0,0 +1,58 @@
+// Large-output handling — mirrors Claude Code's tool-result persistence.
+//
+// When a tool returns more text than the threshold, the full output is written
+// to a file in the workspace and the model receives a <persisted-output>
+// preview + path instead. The model then pages through the full content with
+// read_file (offset/limit). This keeps huge outputs (big greps, verbose builds,
+// long fetches) out of the context window while keeping them fully accessible.
+import { joinPath } from './tools/walk.js';
+/** Default char threshold before a tool result spills to disk (Claude Code uses 50k). */
+export const DEFAULT_MAX_RESULT_CHARS = 50_000;
+/** Bytes of the full output shown inline as a preview. */
+export const PREVIEW_CHARS = 2000;
+/** Directory (relative to cwd) where spilled tool outputs are stored. */
+export const TOOL_RESULTS_DIR = '.bcs/tool-results';
+export const PERSISTED_OUTPUT_TAG = '<persisted-output>';
+export const PERSISTED_OUTPUT_CLOSING_TAG = '</persisted-output>';
+function formatSize(chars) {
+    if (chars < 1024)
+        return `${chars} chars`;
+    if (chars < 1024 * 1024)
+        return `${(chars / 1024).toFixed(1)} KB`;
+    return `${(chars / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Truncate at a newline boundary near the limit when possible. */
+function preview(content) {
+    if (content.length <= PREVIEW_CHARS)
+        return { text: content, hasMore: false };
+    const slice = content.slice(0, PREVIEW_CHARS);
+    const lastNl = slice.lastIndexOf('\n');
+    const cut = lastNl > PREVIEW_CHARS * 0.5 ? slice.slice(0, lastNl) : slice;
+    return { text: cut, hasMore: true };
+}
+/**
+ * If `content` exceeds `threshold`, write it to a file under the workspace and
+ * return a preview message pointing the model at the path. Otherwise returns
+ * the content unchanged. Failures fall back to returning the original content.
+ */
+export async function maybePersistLargeResult(content, toolUseId, fs, cwd, threshold = DEFAULT_MAX_RESULT_CHARS) {
+    if (!Number.isFinite(threshold) || content.length <= threshold)
+        return content;
+    const relPath = `${TOOL_RESULTS_DIR}/${toolUseId}.txt`;
+    const absPath = joinPath(cwd, relPath);
+    try {
+        await fs.writeFile(absPath, content);
+    }
+    catch {
+        // If we can't persist, leave the content inline (better than losing it).
+        return content;
+    }
+    const { text, hasMore } = preview(content);
+    return (`${PERSISTED_OUTPUT_TAG}\n` +
+        `Output too large (${formatSize(content.length)}). Full output saved to: ${absPath}\n` +
+        `Read it with read_file (use offset/limit to page through), or grep it for what you need.\n\n` +
+        `Preview (first ${formatSize(PREVIEW_CHARS)}):\n` +
+        text +
+        (hasMore ? '\n...' : '') +
+        `\n${PERSISTED_OUTPUT_CLOSING_TAG}`);
+}

package/dist/prompt.d.ts

@@ -0,0 +1,6 @@
+export declare function defaultSystemPrompt(cwd: string): string;
+/**
+ * Default system prompt for a general-purpose sub-agent spawned via the `task`
+ * tool. The sub-agent runs autonomously and returns only its final answer.
+ */
+export declare function defaultSubagentPrompt(cwd: string): string;

package/dist/prompt.js

@@ -0,0 +1,34 @@
+// Default system prompt — a compact, faithful distillation of the Claude Code
+// agent contract. Environment-neutral: the host (WebContainer, local OS, or a
+// cloud sandbox) is described by the caller via appendSystemPrompt when needed.
+export function defaultSystemPrompt(cwd) {
+    return `You are an interactive agent that helps users with software engineering tasks, operating on a real workspace (files + shell) via your tools.
+
+You have access to tools for reading, writing, and editing files, running shell commands, and searching the codebase (glob/grep). Use them to accomplish the user's request.
+
+# Working style
+- Be concise and direct. Do what is asked; nothing more, nothing less.
+- Prefer the dedicated file tools (read_file, write_file, edit_file) over shell commands like cat/sed for file operations.
+- You MUST read a file with read_file before editing it with edit_file.
+- When using edit_file, old_string must match the file exactly. If it is not unique, include more surrounding context or use replace_all.
+- Run independent tool calls together when possible.
+- Verify your work (run tests / commands) when practical before declaring success.
+- Do not add comments to code unless asked or where the intent is non-obvious.
+
+# Environment
+- Working directory: ${cwd}
+- Commands run in the workspace's shell; use commands appropriate to the host OS (the caller may specify the platform). The working directory persists between commands.
+
+When the task is complete, stop calling tools and give a short summary of what you did.`;
+}
+/**
+ * Default system prompt for a general-purpose sub-agent spawned via the `task`
+ * tool. The sub-agent runs autonomously and returns only its final answer.
+ */
+export function defaultSubagentPrompt(cwd) {
+    return `You are a general-purpose sub-agent working autonomously on a delegated task in a real workspace (working directory: ${cwd}).
+
+You have the same file, shell, and search tools as the main agent. Work through the task end to end on your own — you cannot ask the user questions.
+
+Your FINAL message is the only thing returned to whoever delegated the task. Make it a complete, self-contained answer: report what you found or did, include the concrete results (paths, values, conclusions), and don't reference "the task" abstractly. Be concise and factual.`;
+}

package/dist/query.d.ts

@@ -0,0 +1,105 @@
+import type { AgentDefinition, CanUseTool, HookCallback, HookEvent, LLMClient, PermissionMode, SDKMessage, SDKUserMessage } from './types/index.js';
+import type { FileReadLimits, Tool } from './tools/types.js';
+import type { McpServers, McpProxy } from './mcp/index.js';
+import type { SlashCommand } from './commands/index.js';
+import type { SessionStore } from './session/index.js';
+import type { MemoryStore } from './memory/index.js';
+import { type Workspace } from './agent.js';
+export interface QueryOptions {
+    /** A plain string (single turn) or a stream of user messages (multi-turn). */
+    prompt: string | AsyncIterable<SDKUserMessage>;
+    /** Workspace implementing FileSystem + CommandExecutor (e.g. WebContainerWorkspace). */
+    workspace: Workspace;
+    /** Any OpenAI/Anthropic-compatible LLM client. */
+    llm: LLMClient;
+    /** Tools available to the agent. REPLACES the builtins. Defaults to ALL_CLAUDE_CODE_TOOLS. */
+    tools?: Tool[];
+    /** Custom tools ADDED to the builtins (use `defineTool`). Filtered by allowed/disallowedTools. */
+    extraTools?: Tool[];
+    model?: string;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    maxTurns?: number;
+    cwd?: string;
+    sessionId?: string;
+    abortController?: AbortController;
+    /** Permission gate invoked before each tool call. */
+    canUseTool?: CanUseTool;
+    permissionMode?: PermissionMode;
+    /** Lifecycle hooks keyed by event. */
+    hooks?: Partial<Record<HookEvent, HookCallback[]>>;
+    /** File-read tuning passed to tools. */
+    limits?: Partial<FileReadLimits>;
+    /** Custom sub-agents invokable via the `task` tool, keyed by type name. */
+    agents?: Record<string, AgentDefinition>;
+    /** Max sub-agent nesting depth. Default 2. */
+    maxSubagentDepth?: number;
+    /** External MCP servers (HTTP/SSE) or in-process SDK servers. */
+    mcpServers?: McpServers;
+    /** Route remote MCP requests through a proxy (works around browser CORS). */
+    mcpProxy?: McpProxy;
+    /** Custom slash commands (merged with built-ins like /help, /compact). */
+    commands?: SlashCommand[];
+    /** Enable background tasks (task_list/task_output/task_stop + task run_in_background). */
+    background?: boolean;
+    /** Inject a shared BackgroundTaskManager so background tasks persist across turns. */
+    backgroundManager?: import('./background/index.js').BackgroundTaskManager;
+    /** Queue for interjecting user messages into the live loop (delivered one per turn boundary). */
+    messageQueue?: import('./queue.js').MessageQueue;
+    /** Emit `stream_event` partial-assistant messages (text deltas) as they arrive. */
+    includePartialMessages?: boolean;
+    /** Enable teammate coordination (shared mailbox + task board + team tools + coordinator prompt). */
+    team?: boolean;
+    /** Inject a shared Mailbox so team messaging persists across turns. */
+    mailbox?: import('./team/index.js').Mailbox;
+    /** Inject a shared TaskBoard so the task board persists across turns. */
+    board?: import('./team/index.js').TaskBoard;
+    /** This agent's name/label for messaging (default 'coordinator'). */
+    agentName?: string;
+    /** Persist the transcript to this store (keyed by sessionId) for resume. */
+    sessionStore?: SessionStore;
+    /** Load the stored transcript for sessionId before the first turn. */
+    resume?: boolean;
+    /** Auto-compact the transcript when it nears the context limit. */
+    autoCompact?: boolean;
+    /** Context window in tokens for auto-compaction (default: model window or 200k). */
+    contextLimit?: number;
+    /** Fraction of the context limit that triggers compaction (default 0.8). */
+    compactThreshold?: number;
+    /** Persistent memory store; entries load into the system prompt and are editable via memory tools. */
+    memory?: MemoryStore;
+    /** Permission rules (allow/deny/ask rule strings) → builds a canUseTool gate. */
+    permissionRules?: {
+        allow?: string[];
+        deny?: string[];
+        ask?: string[];
+    };
+    /** Prompt callback for 'ask' permission decisions. */
+    onPermissionAsk?: (toolName: string, input: Record<string, unknown>) => Promise<boolean>;
+    /** 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[]. */
+    skills?: boolean | import('./skills/index.js').Skill[];
+}
+/** An async iterator of SDK messages, augmented with session controls. */
+export interface Query extends AsyncGenerator<SDKMessage, void, void> {
+    /** Abort the in-flight run (stops the LLM stream and pending tools). */
+    interrupt(): void;
+}
+export declare function query(options: QueryOptions): Query;
+/** Wrap a single text prompt into the async-iterable form runAgent expects. */
+export declare function singlePrompt(text: string): AsyncIterable<SDKUserMessage>;
+/**
+ * A simple push-based prompt queue for interactive sessions. Feed user turns
+ * with `.push(text)` and end the conversation with `.end()`.
+ */
+export declare class PromptStream implements AsyncIterable<SDKUserMessage> {
+    private queue;
+    private resolvers;
+    private done;
+    push(content: string | SDKUserMessage['message']['content']): void;
+    end(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SDKUserMessage>;
+}

package/dist/query.js

@@ -0,0 +1,115 @@
+// Public entry point — mirrors @anthropic-ai/claude-agent-sdk's query().
+//
+// Returns an AsyncGenerator<SDKMessage>. Accepts either a single string prompt
+// or an async iterable of SDKUserMessage (for multi-turn / interactive use).
+import { runAgent } from './agent.js';
+export function query(options) {
+    const prompt = typeof options.prompt === 'string'
+        ? singlePrompt(options.prompt)
+        : options.prompt;
+    const abortController = options.abortController ?? new AbortController();
+    const gen = runAgent({
+        prompt,
+        workspace: options.workspace,
+        llm: options.llm,
+        tools: options.tools,
+        extraTools: options.extraTools,
+        model: options.model,
+        systemPrompt: options.systemPrompt,
+        appendSystemPrompt: options.appendSystemPrompt,
+        allowedTools: options.allowedTools,
+        disallowedTools: options.disallowedTools,
+        maxTurns: options.maxTurns,
+        cwd: options.cwd,
+        sessionId: options.sessionId,
+        abortController,
+        canUseTool: options.canUseTool,
+        permissionMode: options.permissionMode,
+        hooks: options.hooks,
+        limits: options.limits,
+        agents: options.agents,
+        maxSubagentDepth: options.maxSubagentDepth,
+        mcpServers: options.mcpServers,
+        mcpProxy: options.mcpProxy,
+        commands: options.commands,
+        background: options.background,
+        backgroundManager: options.backgroundManager,
+        messageQueue: options.messageQueue,
+        includePartialMessages: options.includePartialMessages,
+        team: options.team,
+        mailbox: options.mailbox,
+        board: options.board,
+        agentName: options.agentName,
+        sessionStore: options.sessionStore,
+        resume: options.resume,
+        autoCompact: options.autoCompact,
+        contextLimit: options.contextLimit,
+        compactThreshold: options.compactThreshold,
+        memory: options.memory,
+        permissionRules: options.permissionRules,
+        onPermissionAsk: options.onPermissionAsk,
+        settings: options.settings,
+        skills: options.skills,
+    });
+    gen.interrupt = () => abortController.abort();
+    return gen;
+}
+/** Wrap a single text prompt into the async-iterable form runAgent expects. */
+export async function* singlePrompt(text) {
+    yield {
+        type: 'user',
+        message: { role: 'user', content: text },
+        parent_tool_use_id: null,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * A simple push-based prompt queue for interactive sessions. Feed user turns
+ * with `.push(text)` and end the conversation with `.end()`.
+ */
+export class PromptStream {
+    constructor() {
+        this.queue = [];
+        this.resolvers = [];
+        this.done = false;
+    }
+    push(content) {
+        const message = {
+            type: 'user',
+            message: {
+                role: 'user',
+                content: typeof content === 'string' ? content : content,
+            },
+            parent_tool_use_id: null,
+            timestamp: new Date().toISOString(),
+        };
+        const r = this.resolvers.shift();
+        if (r)
+            r({ value: message, done: false });
+        else
+            this.queue.push(message);
+    }
+    end() {
+        this.done = true;
+        let r = this.resolvers.shift();
+        while (r) {
+            r({ value: undefined, done: true });
+            r = this.resolvers.shift();
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const queued = this.queue.shift();
+                if (queued)
+                    return Promise.resolve({ value: queued, done: false });
+                if (this.done)
+                    return Promise.resolve({
+                        value: undefined,
+                        done: true,
+                    });
+                return new Promise((resolve) => this.resolvers.push(resolve));
+            },
+        };
+    }
+}