bashkit 0.1.1 → 0.1.3

package/AGENTS.md

@@ -122,7 +122,7 @@ await sandbox.destroy();
 
 ## Sub-agents with Task Tool
 
-The Task tool spawns new `generateText` calls for complex subtasks:
+The Task tool spawns new agents for complex subtasks:
 
 ```typescript
 import { createTaskTool } from "bashkit";
@@ -157,6 +157,40 @@ The parent agent calls Task like any other tool:
 }}
 ```
 
+### Streaming Sub-agent Activity to UI
+
+Pass a `streamWriter` to stream real-time sub-agent activity:
+
+```typescript
+import { createUIMessageStream } from "ai";
+
+const stream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    const taskTool = createTaskTool({
+      model,
+      tools: sandboxTools,
+      streamWriter: writer, // Enable real-time streaming
+      subagentTypes: { ... },
+    });
+
+    const result = streamText({
+      model,
+      tools: { Task: taskTool },
+      ...
+    });
+
+    writer.merge(result.toUIMessageStream());
+  },
+});
+```
+
+When `streamWriter` is provided:
+- Uses `streamText` internally (instead of `generateText`)
+- Emits `data-subagent` events: `start`, `tool-call`, `done`, `complete`
+- Events appear in `message.parts` as `{ type: "data-subagent", data: SubagentEventData }`
+
+**Note:** TaskOutput does NOT include messages (to avoid context bloat). The UI accesses the full conversation via the streamed `complete` event.
+
 ## Prompt Caching
 
 Enable Anthropic prompt caching to reduce costs on repeated prefixes:

package/README.md

@@ -219,7 +219,7 @@ const { tools, planModeState } = createAgentTools(sandbox, {
 
 ## Sub-agents with Task Tool
 
-The Task tool spawns new `generateText` calls for complex subtasks:
+The Task tool spawns new agents for complex subtasks:
 
 ```typescript
 import { createTaskTool } from 'bashkit';
@@ -254,6 +254,46 @@ The parent agent calls Task like any other tool:
 }}
 ```
 
+### Streaming Sub-agent Activity to UI
+
+Pass a `streamWriter` to stream real-time sub-agent activity to the UI:
+
+```typescript
+import { createUIMessageStream } from 'ai';
+
+const stream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    const taskTool = createTaskTool({
+      model,
+      tools: sandboxTools,
+      streamWriter: writer, // Enable real-time streaming
+      subagentTypes: { ... },
+    });
+
+    // Use with streamText
+    const result = streamText({
+      model,
+      tools: { Task: taskTool },
+      ...
+    });
+
+    writer.merge(result.toUIMessageStream());
+  },
+});
+```
+
+When `streamWriter` is provided:
+- Uses `streamText` internally (instead of `generateText`)
+- Emits `data-subagent` events to the UI stream:
+  - `start` - Sub-agent begins work
+  - `tool-call` - Each tool the sub-agent uses (with args)
+  - `done` - Sub-agent finished
+  - `complete` - Full messages array for UI access
+
+These appear in `message.parts` on the client as `{ type: "data-subagent", data: SubagentEventData }`.
+
+**Important:** The TaskOutput returned to the lead agent does NOT include messages (to avoid context bloat). The UI accesses the full conversation via the streamed `complete` event.
+
 ## Context Management
 
 ### Conversation Compaction

package/dist/index.d.ts

@@ -1,8 +1,9 @@
+export type { UIMessageStreamWriter } from "ai";
 export { anthropicPromptCacheMiddleware } from "./middleware";
 export type { E2BSandboxConfig, LocalSandboxConfig, VercelSandboxConfig, } from "./sandbox";
 export { createE2BSandbox, createLocalSandbox, createVercelSandbox, } from "./sandbox";
 export type { ExecOptions, ExecResult, Sandbox } from "./sandbox/interface";
-export type { AgentToolsResult, AskUserError, AskUserOutput, AskUserResponseHandler, BashError, BashOutput, EditError, EditOutput, EnterPlanModeError, EnterPlanModeOutput, ExitPlanModeError, ExitPlanModeOutput, PlanModeState, GlobError, GlobOutput, GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, GrepMatch, GrepOutput, ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, SkillError, SkillOutput, SkillToolConfig, SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, TodoItem, TodoState, TodoWriteError, TodoWriteOutput, WebFetchError, WebFetchOutput, WebFetchToolConfig, WebSearchError, WebSearchOutput, WebSearchResult, WebSearchToolConfig, WriteError, WriteOutput, } from "./tools";
+export type { AgentToolsResult, AskUserError, AskUserOutput, AskUserResponseHandler, BashError, BashOutput, EditError, EditOutput, EnterPlanModeError, EnterPlanModeOutput, ExitPlanModeError, ExitPlanModeOutput, PlanModeState, GlobError, GlobOutput, GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, GrepMatch, GrepOutput, ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, SkillError, SkillOutput, SkillToolConfig, SubagentEventData, SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, TodoItem, TodoState, TodoWriteError, TodoWriteOutput, WebFetchError, WebFetchOutput, WebFetchToolConfig, WebSearchError, WebSearchOutput, WebSearchResult, WebSearchToolConfig, WriteError, WriteOutput, } from "./tools";
 export { createAgentTools, createAskUserTool, createBashTool, createEditTool, createEnterPlanModeTool, createExitPlanModeTool, createGlobTool, createGrepTool, createReadTool, createSkillTool, createTaskTool, createTodoWriteTool, createWebFetchTool, createWebSearchTool, createWriteTool, } from "./tools";
 export type { AgentConfig, AskUserConfig, SkillConfig, ToolConfig, WebFetchConfig, WebSearchConfig, } from "./types";
 export { DEFAULT_CONFIG } from "./types";

package/dist/index.js

@@ -361,10 +361,27 @@ var DEFAULT_CONFIG = {
 // src/tools/ask-user.ts
 import { tool, zodSchema } from "ai";
 import { z } from "zod";
+var questionOptionSchema = z.object({
+  label: z.string().describe("The display text for this option. Should be concise (1-5 words). Add '(Recommended)' suffix for suggested options."),
+  description: z.string().optional().describe("Explanation of what this option means or its implications.")
+});
+var structuredQuestionSchema = z.object({
+  header: z.string().optional().describe("Very short label displayed as a chip/tag (max 12 chars). Examples: 'Auth method', 'Library', 'Approach'."),
+  question: z.string().describe("The complete question to ask the user. Should be clear and specific."),
+  options: z.array(questionOptionSchema).min(2).max(4).optional().describe("Available choices for this question. 2-4 options. An 'Other' option is automatically available to users."),
+  multiSelect: z.boolean().optional().describe("Set to true to allow the user to select multiple options instead of just one.")
+});
 var askUserInputSchema = z.object({
-  question: z.string().describe("The question to ask the user. Be specific and concise.")
+  question: z.string().optional().describe("Simple question string (for backward compatibility). Use 'questions' for structured multi-choice."),
+  questions: z.array(structuredQuestionSchema).min(1).max(4).optional().describe("Structured questions with options (1-4 questions).")
 });
-var ASK_USER_DESCRIPTION = `Ask the user a clarifying question when you need more information to proceed.
+var ASK_USER_DESCRIPTION = `Use this tool when you need to ask the user questions during execution.
+
+**Capabilities:**
+- Gather user preferences or requirements
+- Clarify ambiguous instructions
+- Get decisions on implementation choices
+- Offer choices about what direction to take
 
 **When to use:**
 - You need clarification on ambiguous requirements
@@ -377,23 +394,54 @@ var ASK_USER_DESCRIPTION = `Ask the user a clarifying question when you need mor
 - The question is trivial or can be inferred
 - You're just being overly cautious
 
-Keep questions specific and actionable. Avoid yes/no questions when you need details.`;
-function createAskUserTool(onQuestion) {
+**Simple question format:**
+Use the 'question' parameter for a single free-form question.
+
+**Structured questions format:**
+Use the 'questions' parameter for multiple-choice questions with options:
+- 1-4 questions allowed
+- Each question can have 2-4 options with labels and descriptions
+- Use multiSelect: true to allow multiple answers
+- Users can always select "Other" to provide custom text input
+- Place recommended option first and add "(Recommended)" to label`;
+function createAskUserTool(config) {
+  const normalizedConfig = typeof config === "function" ? { onQuestion: config } : config ?? {};
   return tool({
     description: ASK_USER_DESCRIPTION,
     inputSchema: zodSchema(askUserInputSchema),
-    execute: async ({
-      question
-    }) => {
+    execute: async (input) => {
       try {
-        if (onQuestion) {
-          const answer = await onQuestion(question);
-          return { answer };
+        if (!input.question && !input.questions) {
+          return {
+            error: "Either 'question' or 'questions' must be provided"
+          };
         }
-        return {
-          question,
-          awaiting_response: true
-        };
+        if (input.questions && input.questions.length > 0) {
+          if (normalizedConfig.onStructuredQuestions) {
+            const answers = await normalizedConfig.onStructuredQuestions(input.questions);
+            const firstKey = Object.keys(answers)[0];
+            const firstAnswer = answers[firstKey];
+            return {
+              answer: Array.isArray(firstAnswer) ? firstAnswer.join(", ") : firstAnswer,
+              answers
+            };
+          }
+          return {
+            questions: input.questions,
+            awaiting_response: true
+          };
+        }
+        if (input.question) {
+          if (normalizedConfig.onQuestion) {
+            const answer = await normalizedConfig.onQuestion(input.question);
+            return { answer };
+          }
+          return {
+            question: input.question,
+            awaiting_response: true
+          };
+        }
+        return { error: "No question provided" };
       } catch (error) {
         return {
           error: error instanceof Error ? error.message : "Unknown error"
@@ -412,15 +460,40 @@ var bashInputSchema = z2.object({
   description: z2.string().optional().describe("Clear, concise description of what this command does in 5-10 words"),
   run_in_background: z2.boolean().optional().describe("Set to true to run this command in the background")
 });
-var BASH_DESCRIPTION = `Executes bash commands in a persistent shell session with optional timeout and background execution.
+var BASH_DESCRIPTION = `Executes a bash command in a persistent shell session with optional timeout.
 
-**Important guidelines:**
-- Always quote file paths containing spaces with double quotes (e.g., cd "/path/with spaces")
-- Avoid using search commands like \`find\` and \`grep\` - use the Glob and Grep tools instead
-- Avoid using \`cat\`, \`head\`, \`tail\` - use the Read tool instead
-- When issuing multiple commands, use \`;\` or \`&&\` to separate them (not newlines)
-- If output exceeds 30000 characters, it will be truncated
-- Default timeout is 2 minutes; maximum is 10 minutes`;
+IMPORTANT: For file operations (reading, writing, editing, searching, finding files) - use the specialized tools instead of bash commands.
+
+Before executing the command, please follow these steps:
+
+1. Directory Verification:
+   - If the command will create new directories or files, first use \`ls\` to verify the parent directory exists and is the correct location
+   - For example, before running "mkdir foo/bar", first use \`ls foo\` to check that "foo" exists
+
+2. Command Execution:
+   - Always quote file paths that contain spaces with double quotes (e.g., cd "/path/with spaces")
+   - Examples of proper quoting:
+     - cd "/Users/name/My Documents" (correct)
+     - cd /Users/name/My Documents (incorrect - will fail)
+   - After ensuring proper quoting, execute the command
+
+Usage notes:
+  - The command argument is required
+  - You can specify an optional timeout in milliseconds (max 600000ms / 10 minutes). Default is 120000ms (2 minutes).
+  - It is very helpful if you write a clear, concise description of what this command does in 5-10 words
+  - If the output exceeds 30000 characters, output will be truncated
+  - Avoid using \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands. Instead, use dedicated tools:
+    - File search: Use Glob (NOT find or ls)
+    - Content search: Use Grep (NOT grep or rg)
+    - Read files: Use Read (NOT cat/head/tail)
+    - Edit files: Use Edit (NOT sed/awk)
+    - Write files: Use Write (NOT echo >/cat <<EOF)
+  - When issuing multiple commands:
+    - If commands are independent, make multiple Bash tool calls in parallel
+    - If commands depend on each other, use '&&' to chain them (e.g., \`git add . && git commit -m "message"\`)
+    - Use ';' only when you need sequential execution but don't care if earlier commands fail
+    - DO NOT use newlines to separate commands
+  - Try to maintain your current working directory by using absolute paths and avoiding \`cd\``;
 function createBashTool(sandbox, config) {
   const maxOutputLength = config?.maxOutputLength ?? 30000;
   const defaultTimeout = config?.timeout ?? 120000;
@@ -482,9 +555,26 @@ var editInputSchema = z3.object({
   new_string: z3.string().describe("The text to replace it with (must be different from old_string)"),
   replace_all: z3.boolean().optional().describe("Replace all occurrences of old_string (default false)")
 });
+var EDIT_DESCRIPTION = `Performs exact string replacements in files.
+
+**Important guidelines:**
+- You MUST use the Read tool first before editing any file
+- Preserve exact indentation (tabs/spaces) when replacing text
+- The old_string must be unique in the file, or the edit will fail
+- If old_string appears multiple times, either provide more context to make it unique, or use replace_all=true
+
+**Parameters:**
+- old_string: The exact text to find and replace (must match exactly, including whitespace)
+- new_string: The replacement text (must be different from old_string)
+- replace_all: Set to true to replace all occurrences (useful for renaming variables)
+
+**When to use:**
+- Making targeted changes to existing files
+- Renaming variables or functions (with replace_all=true)
+- Updating specific sections`;
 function createEditTool(sandbox, config) {
   return tool3({
-    description: "Performs exact string replacements in files.",
+    description: EDIT_DESCRIPTION,
     inputSchema: zodSchema3(editInputSchema),
     execute: async ({
       file_path,
@@ -546,24 +636,61 @@ import { z as z4 } from "zod";
 var enterPlanModeInputSchema = z4.object({
   reason: z4.string().describe("Brief explanation of why you're entering planning mode (e.g., 'Need to explore codebase architecture before implementing feature')")
 });
-var ENTER_PLAN_MODE_DESCRIPTION = `Enter planning mode to explore and design implementation approaches before making changes.
+var ENTER_PLAN_MODE_DESCRIPTION = `Use this tool proactively when you're about to start a non-trivial task. Getting user sign-off on your approach prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore and design an approach for user approval.
 
-**When to use:**
-- Complex tasks requiring research or exploration
-- Need to understand codebase structure before implementing
-- Multiple approaches possible and you need to evaluate trade-offs
-- User explicitly asks you to plan before executing
+## When to Use This Tool
 
-**In planning mode:**
-- Focus on reading, searching, and understanding
-- Avoid making file changes (use Read, Grep, Glob instead of Write, Edit)
-- Document your findings and proposed approach
-- Use ExitPlanMode when ready with a plan for user approval
+**Prefer using EnterPlanMode** for tasks unless they're simple. Use it when ANY of these conditions apply:
 
-**When NOT to use:**
-- Simple, well-defined tasks
-- You already understand the codebase and approach
-- User wants immediate execution`;
+1. **New Functionality**: Adding meaningful new capabilities
+   - Example: "Add a new report" - what format? What data?
+   - Example: "Add validation" - what rules? What error messages?
+
+2. **Multiple Valid Approaches**: The task can be solved in several different ways
+   - Example: "Add caching" - could use Redis, in-memory, file-based, etc.
+   - Example: "Improve performance" - many optimization strategies possible
+
+3. **Modifications**: Changes that affect existing behavior or structure
+   - Example: "Update the workflow" - what exactly should change?
+   - Example: "Refactor this component" - what's the target architecture?
+
+4. **Architectural Decisions**: The task requires choosing between patterns or technologies
+   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
+   - Example: "Implement state management" - different approaches possible
+
+5. **Multi-File Changes**: The task will likely touch more than 2-3 files
+
+6. **Unclear Requirements**: You need to explore before understanding the full scope
+   - Example: "Make this faster" - need to profile and identify bottlenecks
+   - Example: "Fix the bug" - need to investigate root cause
+
+7. **User Preferences Matter**: The approach could reasonably go multiple ways
+   - If you would use AskUser to clarify the approach, use EnterPlanMode instead
+   - Plan mode lets you explore first, then present options with context
+
+## When NOT to Use This Tool
+
+Only skip EnterPlanMode for simple tasks:
+- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
+- Adding a single function with clear requirements
+- Tasks where the user has given very specific, detailed instructions
+- Pure research/exploration tasks
+
+## What Happens in Plan Mode
+
+In plan mode, you'll:
+1. Thoroughly explore using Glob, Grep, and Read tools
+2. Understand existing patterns and architecture
+3. Design an approach
+4. Present your plan to the user for approval
+5. Use AskUser if you need to clarify approaches
+6. Exit plan mode with ExitPlanMode when ready to execute
+
+## Important Notes
+
+- This tool REQUIRES user approval - they must consent to entering plan mode
+- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
+- Users appreciate being consulted before significant changes`;
 function createEnterPlanModeTool(state, onEnter) {
   return tool4({
     description: ENTER_PLAN_MODE_DESCRIPTION,
@@ -602,9 +729,30 @@ import { z as z5 } from "zod";
 var exitPlanModeInputSchema = z5.object({
   plan: z5.string().describe("The plan to present to the user for approval")
 });
+var EXIT_PLAN_MODE_DESCRIPTION = `Use this tool when you are in plan mode and have finished planning and are ready for user approval.
+
+## How This Tool Works
+- Pass your completed plan as a parameter
+- This tool signals that you're done planning and ready for the user to review
+- The user will see your plan and can approve or request changes
+
+## When to Use This Tool
+IMPORTANT: Only use this tool when the task requires planning implementation steps. For research tasks where you're gathering information, searching files, or understanding the codebase - do NOT use this tool.
+
+## Handling Ambiguity in Plans
+Before using this tool, ensure your plan is clear and unambiguous. If there are multiple valid approaches or unclear requirements:
+1. Ask the user to clarify (use AskUser tool if available)
+2. Ask about specific implementation choices (e.g., architectural patterns, which library to use)
+3. Clarify any assumptions that could affect the implementation
+4. Only proceed with ExitPlanMode after resolving ambiguities
+
+## Examples
+1. "Search for and understand the implementation of X" - Do NOT use this tool (research task)
+2. "Help me implement feature Y" - Use this tool after planning the implementation steps
+3. "Add user authentication" - If unsure about approach (OAuth vs JWT), clarify first, then use this tool`;
 function createExitPlanModeTool(config, onPlanSubmit) {
   return tool5({
-    description: "Exits planning mode and prompts the user to approve the plan. Use this when you have finished planning and want user confirmation before proceeding.",
+    description: EXIT_PLAN_MODE_DESCRIPTION,
     inputSchema: zodSchema5(exitPlanModeInputSchema),
     execute: async ({
       plan
@@ -634,9 +782,17 @@ var globInputSchema = z6.object({
   pattern: z6.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js", "*.md")'),
   path: z6.string().optional().describe("Directory to search in (defaults to working directory)")
 });
+var GLOB_DESCRIPTION = `
+- Fast file pattern matching tool that works with any codebase size
+- Supports glob patterns like "**/*.js" or "src/**/*.ts"
+- Returns matching file paths sorted by modification time
+- Use this tool when you need to find files by name patterns
+- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Task tool instead
+- It is always better to speculatively perform multiple searches in parallel if they are potentially useful
+`;
 function createGlobTool(sandbox, config) {
   return tool6({
-    description: "Search for files matching a glob pattern. Returns file paths sorted by modification time. Use this instead of `find` command.",
+    description: GLOB_DESCRIPTION,
     inputSchema: zodSchema6(globInputSchema),
     execute: async ({
       pattern,
@@ -674,22 +830,46 @@ function createGlobTool(sandbox, config) {
 import { tool as tool7, zodSchema as zodSchema7 } from "ai";
 import { z as z7 } from "zod";
 var grepInputSchema = z7.object({
-  pattern: z7.string().describe("The regular expression pattern to search for"),
+  pattern: z7.string().describe("The regular expression pattern to search for in file contents"),
   path: z7.string().optional().describe("File or directory to search in (defaults to cwd)"),
-  glob: z7.string().optional().describe('Glob pattern to filter files (e.g. "*.js")'),
+  glob: z7.string().optional().describe('Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")'),
   type: z7.string().optional().describe('File type to search (e.g. "js", "py", "rust")'),
-  output_mode: z7.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content", "files_with_matches", or "count"'),
+  output_mode: z7.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts'),
   "-i": z7.boolean().optional().describe("Case insensitive search"),
-  "-n": z7.boolean().optional().describe("Show line numbers (for content mode)"),
-  "-B": z7.number().optional().describe("Lines to show before each match"),
-  "-A": z7.number().optional().describe("Lines to show after each match"),
-  "-C": z7.number().optional().describe("Lines to show before and after each match"),
-  head_limit: z7.number().optional().describe("Limit output to first N lines/entries"),
-  multiline: z7.boolean().optional().describe("Enable multiline mode")
+  "-n": z7.boolean().optional().describe("Show line numbers in output. Requires output_mode: 'content'. Defaults to true."),
+  "-B": z7.number().optional().describe("Number of lines to show before each match. Requires output_mode: 'content'."),
+  "-A": z7.number().optional().describe("Number of lines to show after each match. Requires output_mode: 'content'."),
+  "-C": z7.number().optional().describe("Number of lines to show before and after each match. Requires output_mode: 'content'."),
+  head_limit: z7.number().optional().describe("Limit output to first N lines/entries. Works across all output modes. Defaults to 0 (unlimited)."),
+  offset: z7.number().optional().describe("Skip first N lines/entries before applying head_limit. Works across all output modes. Defaults to 0."),
+  multiline: z7.boolean().optional().describe("Enable multiline mode where patterns can span lines (requires ripgrep). Default: false.")
 });
+var GREP_DESCRIPTION = `A powerful content search tool with regex support. Use this instead of running grep commands directly.
+
+**Usage:**
+- ALWAYS use Grep for search tasks. NEVER invoke \`grep\` or \`rg\` as a Bash command.
+- Supports regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
+
+**Output modes:**
+- "content": Shows matching lines with optional context
+- "files_with_matches": Shows only file paths (default)
+- "count": Shows match counts per file
+
+**Context options (content mode only):**
+- -B: Lines to show before each match
+- -A: Lines to show after each match
+- -C: Lines to show before and after each match
+
+**Pagination:**
+- Use offset to skip results (useful for pagination)
+- Use head_limit to limit total results returned
+
+**Note:** Set useRipgrep: true in config for better performance and multiline support (requires ripgrep installed).`;
 function createGrepTool(sandbox, config) {
+  const useRipgrep = config?.useRipgrep ?? false;
   return tool7({
-    description: "Powerful search tool built on ripgrep with regex support. Use this instead of the grep command.",
+    description: GREP_DESCRIPTION,
     inputSchema: zodSchema7(grepInputSchema),
     execute: async (input) => {
       const {
@@ -697,13 +877,14 @@ function createGrepTool(sandbox, config) {
         path,
         glob,
         type,
-        output_mode = "content",
+        output_mode = "files_with_matches",
         "-i": caseInsensitive,
         "-n": showLineNumbers = true,
         "-B": beforeContext,
         "-A": afterContext,
         "-C": context,
         head_limit,
+        offset = 0,
         multiline
       } = input;
       const searchPath = path || ".";
@@ -713,32 +894,52 @@ function createGrepTool(sandbox, config) {
           return { error: `Path not allowed: ${searchPath}` };
         }
       }
+      if (multiline && !useRipgrep) {
+        return {
+          error: "Multiline mode requires ripgrep. Set useRipgrep: true in config."
+        };
+      }
       try {
-        const flags = [];
-        if (caseInsensitive)
-          flags.push("-i");
-        if (showLineNumbers && output_mode === "content")
-          flags.push("-n");
-        if (multiline)
-          flags.push("-U");
-        if (context) {
-          flags.push(`-C ${context}`);
-        } else {
-          if (beforeContext)
-            flags.push(`-B ${beforeContext}`);
-          if (afterContext)
-            flags.push(`-A ${afterContext}`);
+        let paginationSuffix = "";
+        if (offset > 0) {
+          paginationSuffix += ` | tail -n +${offset + 1}`;
+        }
+        if (head_limit && head_limit > 0) {
+          paginationSuffix += ` | head -${head_limit}`;
         }
-        if (glob)
-          flags.push(`--include="${glob}"`);
-        if (type)
-          flags.push(`--include="*.${type}"`);
-        const flagStr = flags.join(" ");
-        const limit = head_limit || 1000;
         let cmd;
+        if (useRipgrep) {
+          cmd = buildRipgrepCommand({
+            pattern,
+            searchPath,
+            output_mode,
+            caseInsensitive,
+            showLineNumbers,
+            beforeContext,
+            afterContext,
+            context,
+            glob,
+            type,
+            multiline,
+            paginationSuffix
+          });
+        } else {
+          cmd = buildGrepCommand({
+            pattern,
+            searchPath,
+            output_mode,
+            caseInsensitive,
+            showLineNumbers,
+            beforeContext,
+            afterContext,
+            context,
+            glob,
+            type,
+            paginationSuffix
+          });
+        }
+        const result = await sandbox.exec(cmd, { timeout: config?.timeout });
         if (output_mode === "files_with_matches") {
-          cmd = `grep -rl ${flagStr} "${pattern}" ${searchPath} 2>/dev/null | head -${limit}`;
-          const result = await sandbox.exec(cmd, { timeout: config?.timeout });
           const files = result.stdout.split(`
 `).filter(Boolean);
           return {
@@ -746,8 +947,6 @@ function createGrepTool(sandbox, config) {
             count: files.length
           };
         } else if (output_mode === "count") {
-          cmd = `grep -rc ${flagStr} "${pattern}" ${searchPath} 2>/dev/null | grep -v ':0$' | head -${limit}`;
-          const result = await sandbox.exec(cmd, { timeout: config?.timeout });
           const lines = result.stdout.split(`
 `).filter(Boolean);
           const counts = lines.map((line) => {
@@ -763,8 +962,6 @@ function createGrepTool(sandbox, config) {
             total
           };
         } else {
-          cmd = `grep -rn ${flagStr} "${pattern}" ${searchPath} 2>/dev/null | head -${limit}`;
-          const result = await sandbox.exec(cmd, { timeout: config?.timeout });
           if (!result.stdout.trim()) {
             return {
               matches: [],
@@ -798,6 +995,66 @@ function createGrepTool(sandbox, config) {
     }
   });
 }
+function buildRipgrepCommand(opts) {
+  const flags = [];
+  if (opts.caseInsensitive)
+    flags.push("-i");
+  if (opts.multiline)
+    flags.push("-U", "--multiline-dotall");
+  if (opts.output_mode === "content") {
+    if (opts.showLineNumbers)
+      flags.push("-n");
+    if (opts.context) {
+      flags.push(`-C ${opts.context}`);
+    } else {
+      if (opts.beforeContext)
+        flags.push(`-B ${opts.beforeContext}`);
+      if (opts.afterContext)
+        flags.push(`-A ${opts.afterContext}`);
+    }
+  }
+  if (opts.glob)
+    flags.push(`-g "${opts.glob}"`);
+  if (opts.type)
+    flags.push(`-t ${opts.type}`);
+  const flagStr = flags.join(" ");
+  if (opts.output_mode === "files_with_matches") {
+    return `rg -l ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
+  } else if (opts.output_mode === "count") {
+    return `rg -c ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
+  } else {
+    return `rg ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
+  }
+}
+function buildGrepCommand(opts) {
+  const flags = ["-r"];
+  if (opts.caseInsensitive)
+    flags.push("-i");
+  if (opts.output_mode === "content") {
+    if (opts.showLineNumbers)
+      flags.push("-n");
+    if (opts.context) {
+      flags.push(`-C ${opts.context}`);
+    } else {
+      if (opts.beforeContext)
+        flags.push(`-B ${opts.beforeContext}`);
+      if (opts.afterContext)
+        flags.push(`-A ${opts.afterContext}`);
+    }
+  }
+  if (opts.glob)
+    flags.push(`--include="${opts.glob}"`);
+  if (opts.type)
+    flags.push(`--include="*.${opts.type}"`);
+  const flagStr = flags.join(" ");
+  if (opts.output_mode === "files_with_matches") {
+    return `grep -l ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
+  } else if (opts.output_mode === "count") {
+    return `grep -c ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null | grep -v ':0$'${opts.paginationSuffix}`;
+  } else {
+    return `grep ${flagStr} "${opts.pattern}" ${opts.searchPath} 2>/dev/null${opts.paginationSuffix}`;
+  }
+}
 
 // src/tools/read.ts
 import { tool as tool8, zodSchema as zodSchema8 } from "ai";
@@ -807,9 +1064,21 @@ var readInputSchema = z8.object({
   offset: z8.number().optional().describe("Line number to start reading from (1-indexed)"),
   limit: z8.number().optional().describe("Maximum number of lines to read")
 });
+var READ_DESCRIPTION = `Reads a file from the local filesystem. You can access any file directly by using this tool.
+Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to 500 lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files)
+- Results are returned with line numbers starting at 1
+- This tool can only read text files, not binary files (images, PDFs, etc.)
+- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
+- It is always better to speculatively read multiple potentially useful files in parallel
+- If you read a file that exists but has empty contents you will receive a warning in place of file contents`;
 function createReadTool(sandbox, config) {
   return tool8({
-    description: "Read the contents of a file or list directory entries. For text files, returns numbered lines with total line count. For directories, returns file/folder names. Use this instead of `cat`, `head`, or `tail` commands.",
+    description: READ_DESCRIPTION,
     inputSchema: zodSchema8(readInputSchema),
     execute: async ({
       file_path,
@@ -972,10 +1241,26 @@ var webFetchInputSchema = z10.object({
   prompt: z10.string().describe("The prompt to run on the fetched content")
 });
 var RETRYABLE_CODES = [408, 429, 500, 502, 503];
+var WEB_FETCH_DESCRIPTION = `
+- Fetches content from a specified URL and processes it using an AI model
+- Takes a URL and a prompt as input
+- Fetches the URL content and extracts text
+- Processes the content with the prompt using the configured model
+- Returns the model's response about the content
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - The prompt should describe what information you want to extract from the page
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large
+  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL. You should then make a new WebFetch request with the redirect URL to fetch the content.
+`;
 function createWebFetchTool(config) {
   const { apiKey, model } = config;
   return tool10({
-    description: "Fetches content from a URL and processes it with an AI model. Use this to analyze web pages, extract information, or summarize content.",
+    description: WEB_FETCH_DESCRIPTION,
     inputSchema: zodSchema10(webFetchInputSchema),
     execute: async (input) => {
       const { url, prompt } = input;
@@ -1045,10 +1330,30 @@ var webSearchInputSchema = z11.object({
   blocked_domains: z11.array(z11.string()).optional().describe("Never include results from these domains")
 });
 var RETRYABLE_CODES2 = [408, 429, 500, 502, 503];
+var WEB_SEARCH_DESCRIPTION = `Searches the web and returns results with links. Use this for accessing up-to-date information beyond your knowledge cutoff.
+
+**Capabilities:**
+- Provides current information for recent events and data
+- Returns results formatted with titles, URLs, and snippets
+- Supports domain filtering to include or block specific websites
+
+**CRITICAL REQUIREMENT - You MUST follow this:**
+After answering using search results, you MUST include a "Sources:" section listing relevant URLs as markdown hyperlinks:
+
+Sources:
+- [Source Title 1](https://example.com/1)
+- [Source Title 2](https://example.com/2)
+
+**Important - Use the correct year:**
+When searching for recent information, documentation, or current events, use the current year in your query (e.g., "React documentation 2025" not "2024").
+
+**Domain filtering:**
+- allowed_domains: Only include results from these domains
+- blocked_domains: Never include results from these domains`;
 function createWebSearchTool(config) {
   const { apiKey } = config;
   return tool11({
-    description: "Searches the web and returns formatted results. Use this to find current information, documentation, articles, and more.",
+    description: WEB_SEARCH_DESCRIPTION,
     inputSchema: zodSchema11(webSearchInputSchema),
     execute: async (input) => {
       const { query, allowed_domains, blocked_domains } = input;
@@ -1101,9 +1406,21 @@ var writeInputSchema = z12.object({
   file_path: z12.string().describe("Path to the file to write"),
   content: z12.string().describe("Content to write to the file")
 });
+var WRITE_DESCRIPTION = `Writes content to a file on the filesystem.
+
+**Important guidelines:**
+- This tool will overwrite existing files at the provided path
+- If modifying an existing file, you MUST use the Read tool first to read the file's contents
+- ALWAYS prefer editing existing files over creating new ones
+- NEVER proactively create documentation files (*.md) or README files unless explicitly requested
+- The file_path must be an absolute path, not relative
+
+**When to use Write vs Edit:**
+- Use Write for creating new files or completely replacing file contents
+- Use Edit for making targeted changes to existing files (preferred for modifications)`;
 function createWriteTool(sandbox, config) {
   return tool12({
-    description: "Write content to a file. Creates the file if it does not exist, overwrites if it does.",
+    description: WRITE_DESCRIPTION,
     inputSchema: zodSchema12(writeInputSchema),
     execute: async ({
       file_path,
@@ -1139,6 +1456,7 @@ function createWriteTool(sandbox, config) {
 // src/tools/task.ts
 import {
   generateText as generateText2,
+  streamText,
   stepCountIs,
   tool as tool13,
   zodSchema as zodSchema13
@@ -1149,6 +1467,30 @@ var taskInputSchema = z13.object({
   prompt: z13.string().describe("The task for the agent to perform"),
   subagent_type: z13.string().describe("The type of specialized agent to use for this task")
 });
+var TASK_DESCRIPTION = `Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The Task tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+**When NOT to use the Task tool:**
+- If you want to read a specific file path, use the Read or Glob tool instead, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead, to find the match more quickly
+- Other tasks that are not related to the available agent types
+
+**Usage notes:**
+- Always include a short description (3-5 words) summarizing what the agent will do
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
+- The agent's outputs should generally be trusted
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.`;
+var eventCounter = 0;
+function generateEventId() {
+  return `subagent-${Date.now()}-${++eventCounter}`;
+}
 function filterTools(allTools, allowedTools) {
   if (!allowedTools)
     return allTools;
@@ -1165,13 +1507,12 @@ function createTaskTool(config) {
     model: defaultModel,
     tools: allTools,
     subagentTypes = {},
-    costPerInputToken = 0.000003,
-    costPerOutputToken = 0.000015,
     defaultStopWhen,
-    defaultOnStepFinish
+    defaultOnStepFinish,
+    streamWriter
   } = config;
   return tool13({
-    description: "Launches a new agent to handle complex, multi-step tasks autonomously. Use this for tasks that require multiple steps, research, or specialized expertise.",
+    description: TASK_DESCRIPTION,
     inputSchema: zodSchema13(taskInputSchema),
     execute: async ({
       description,
@@ -1184,13 +1525,88 @@ function createTaskTool(config) {
         const model = typeConfig.model || defaultModel;
         const tools = filterTools(allTools, typeConfig.tools);
         const systemPrompt = typeConfig.systemPrompt;
-        const result = await generateText2({
+        const commonOptions = {
           model,
           tools,
           system: systemPrompt,
           prompt,
           stopWhen: typeConfig.stopWhen ?? defaultStopWhen ?? stepCountIs(15),
-          prepareStep: typeConfig.prepareStep,
+          prepareStep: typeConfig.prepareStep
+        };
+        if (streamWriter) {
+          const startId = generateEventId();
+          streamWriter.write({
+            type: "data-subagent",
+            id: startId,
+            data: {
+              event: "start",
+              subagent: subagent_type,
+              description
+            }
+          });
+          const result2 = streamText({
+            ...commonOptions,
+            onStepFinish: async (step) => {
+              if (step.toolCalls?.length) {
+                for (const tc of step.toolCalls) {
+                  const eventId = generateEventId();
+                  streamWriter.write({
+                    type: "data-subagent",
+                    id: eventId,
+                    data: {
+                      event: "tool-call",
+                      subagent: subagent_type,
+                      description,
+                      toolName: tc.toolName,
+                      args: tc.input
+                    }
+                  });
+                }
+              }
+              await typeConfig.onStepFinish?.(step);
+              await defaultOnStepFinish?.({
+                subagentType: subagent_type,
+                description,
+                step
+              });
+            }
+          });
+          const text = await result2.text;
+          const usage2 = await result2.usage;
+          const response = await result2.response;
+          streamWriter.write({
+            type: "data-subagent",
+            id: generateEventId(),
+            data: {
+              event: "done",
+              subagent: subagent_type,
+              description
+            }
+          });
+          streamWriter.write({
+            type: "data-subagent",
+            id: generateEventId(),
+            data: {
+              event: "complete",
+              subagent: subagent_type,
+              description,
+              messages: response.messages
+            }
+          });
+          const durationMs2 = Math.round(performance.now() - startTime);
+          return {
+            result: text,
+            usage: usage2.inputTokens !== undefined && usage2.outputTokens !== undefined ? {
+              input_tokens: usage2.inputTokens,
+              output_tokens: usage2.outputTokens
+            } : undefined,
+            duration_ms: durationMs2,
+            subagent: subagent_type,
+            description
+          };
+        }
+        const result = await generateText2({
+          ...commonOptions,
           onStepFinish: async (step) => {
             await typeConfig.onStepFinish?.(step);
             await defaultOnStepFinish?.({
@@ -1205,20 +1621,16 @@ function createTaskTool(config) {
           input_tokens: result.usage.inputTokens,
           output_tokens: result.usage.outputTokens
         } : undefined;
-        let totalCostUsd;
-        if (usage) {
-          totalCostUsd = usage.input_tokens * costPerInputToken + usage.output_tokens * costPerOutputToken;
-        }
         return {
           result: result.text,
           usage,
-          total_cost_usd: totalCostUsd,
-          duration_ms: durationMs
+          duration_ms: durationMs,
+          subagent: subagent_type,
+          description
         };
       } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        return { error: errorMessage };
       }
     }
   });
@@ -1233,9 +1645,41 @@ var todoWriteInputSchema = z14.object({
     activeForm: z14.string().describe("Active form of the task description")
   })).describe("The updated todo list")
 });
+var TODO_WRITE_DESCRIPTION = `Use this tool to create and manage a structured task list for tracking progress. This helps organize complex tasks and gives the user visibility into your work.
+
+**When to use this tool proactively:**
+1. Complex multi-step tasks - When a task requires 3 or more distinct steps
+2. Non-trivial tasks - Tasks requiring careful planning or multiple operations
+3. User explicitly requests a todo list
+4. User provides multiple tasks - Numbered lists or comma-separated items
+5. After receiving new instructions - Immediately capture requirements as todos
+6. When starting work - Mark task as in_progress BEFORE beginning
+7. After completing - Mark as completed and add any follow-up tasks discovered
+
+**When NOT to use:**
+1. Single, straightforward tasks
+2. Trivial tasks with no organizational benefit
+3. Tasks completable in less than 3 trivial steps
+4. Purely conversational or informational requests
+
+**Task states:**
+- pending: Not yet started
+- in_progress: Currently working on (limit to ONE at a time)
+- completed: Finished successfully
+
+**Task format (both required):**
+- content: Imperative form ("Run tests", "Analyze data")
+- activeForm: Present continuous form ("Running tests", "Analyzing data")
+
+**Task management rules:**
+- Update status in real-time as you work
+- Mark complete IMMEDIATELY after finishing (don't batch)
+- Keep exactly ONE task in_progress at any time
+- ONLY mark completed when FULLY accomplished
+- If blocked/errors, keep in_progress and create new task for the blocker`;
 function createTodoWriteTool(state, config, onUpdate) {
   return tool14({
-    description: "Creates and manages a structured task list for tracking progress. Use this to plan complex tasks and track completion.",
+    description: TODO_WRITE_DESCRIPTION,
     inputSchema: zodSchema14(todoWriteInputSchema),
     execute: async ({
       todos

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

@@ -1,23 +1,53 @@
-export interface AskUserOutput {
+export interface QuestionOption {
+    label: string;
+    description?: string;
+}
+export interface StructuredQuestion {
+    header?: string;
+    question: string;
+    options?: QuestionOption[];
+    multiSelect?: boolean;
+}
+export interface AskUserSimpleOutput {
     question: string;
     awaiting_response: true;
 }
+export interface AskUserStructuredOutput {
+    questions: StructuredQuestion[];
+    awaiting_response: true;
+}
+export type AskUserOutput = AskUserSimpleOutput | AskUserStructuredOutput;
 export interface AskUserError {
     error: string;
 }
+export interface AskUserAnswerOutput {
+    answer: string;
+    answers?: Record<string, string | string[]>;
+}
 export type AskUserResponseHandler = (question: string) => Promise<string> | string;
+export type AskUserStructuredHandler = (questions: StructuredQuestion[]) => Promise<Record<string, string | string[]>> | Record<string, string | string[]>;
+export interface AskUserToolConfig {
+    /** Handler for simple string questions */
+    onQuestion?: AskUserResponseHandler;
+    /** Handler for structured questions with options */
+    onStructuredQuestions?: AskUserStructuredHandler;
+}
 /**
  * Creates a tool for asking the user clarifying questions.
  *
- * The response handler can be:
- * - Synchronous: returns the answer immediately
- * - Async: waits for user input (e.g., from a UI)
- * - Undefined: tool returns awaiting_response flag for external handling
+ * Supports both simple string questions and structured multi-choice questions.
  *
- * @param onQuestion - Optional callback to handle the question and return an answer
+ * @param config - Configuration with optional handlers for questions
  */
-export declare function createAskUserTool(onQuestion?: AskUserResponseHandler): import("ai").Tool<{
-    question: string;
-}, AskUserOutput | AskUserError | {
-    answer: string;
-}>;
+export declare function createAskUserTool(config?: AskUserToolConfig | AskUserResponseHandler): import("ai").Tool<{
+    question?: string | undefined;
+    questions?: {
+        question: string;
+        header?: string | undefined;
+        options?: {
+            label: string;
+            description?: string | undefined;
+        }[] | undefined;
+        multiSelect?: boolean | undefined;
+    }[] | undefined;
+}, AskUserOutput | AskUserError | AskUserAnswerOutput>;

package/dist/tools/grep.d.ts

@@ -1,5 +1,5 @@
 import type { Sandbox } from "../sandbox/interface";
-import type { ToolConfig } from "../types";
+import type { GrepToolConfig } from "../types";
 export interface GrepMatch {
     file: string;
     line_number?: number;
@@ -26,7 +26,7 @@ export interface GrepError {
     error: string;
 }
 export type GrepOutput = GrepContentOutput | GrepFilesOutput | GrepCountOutput | GrepError;
-export declare function createGrepTool(sandbox: Sandbox, config?: ToolConfig): import("ai").Tool<{
+export declare function createGrepTool(sandbox: Sandbox, config?: GrepToolConfig): import("ai").Tool<{
     pattern: string;
     path?: string | undefined;
     glob?: string | undefined;
@@ -38,5 +38,6 @@ export declare function createGrepTool(sandbox: Sandbox, config?: ToolConfig): i
     "-A"?: number | undefined;
     "-C"?: number | undefined;
     head_limit?: number | undefined;
+    offset?: number | undefined;
     multiline?: boolean | undefined;
 }, GrepOutput>;

package/dist/tools/index.d.ts

@@ -65,7 +65,7 @@ export type { ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, } from
 export { createReadTool } from "./read";
 export type { SkillError, SkillOutput, SkillToolConfig } from "./skill";
 export { createSkillTool } from "./skill";
-export type { SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, } from "./task";
+export type { SubagentEventData, SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, } from "./task";
 export { createTaskTool } from "./task";
 export type { TodoItem, TodoState, TodoWriteError, TodoWriteOutput, } from "./todo-write";
 export { createTodoWriteTool } from "./todo-write";

package/dist/tools/task.d.ts

@@ -1,12 +1,13 @@
-import { type LanguageModel, type PrepareStepFunction, type StepResult, type StopCondition, type Tool, type ToolSet } from "ai";
+import { type ModelMessage, type LanguageModel, type PrepareStepFunction, type StepResult, type StopCondition, type UIMessageStreamWriter, type Tool, type ToolSet } from "ai";
 export interface TaskOutput {
     result: string;
     usage?: {
         input_tokens: number;
         output_tokens: number;
     };
-    total_cost_usd?: number;
     duration_ms?: number;
+    subagent?: string;
+    description?: string;
 }
 export interface TaskError {
     error: string;
@@ -17,6 +18,15 @@ export interface SubagentStepEvent {
     description: string;
     step: StepResult<ToolSet>;
 }
+/** Data format for streamed subagent events (appears in message.parts as type: "data-subagent") */
+export interface SubagentEventData {
+    event: "start" | "tool-call" | "done" | "complete";
+    subagent: string;
+    description: string;
+    toolName?: string;
+    args?: Record<string, unknown>;
+    messages?: ModelMessage[];
+}
 export interface SubagentTypeConfig {
     /** Model to use for this subagent type */
     model?: LanguageModel;
@@ -38,13 +48,11 @@ export interface TaskToolConfig {
     tools: ToolSet;
     /** Configuration for each subagent type */
     subagentTypes?: Record<string, SubagentTypeConfig>;
-    /** Cost per input token for usage tracking */
-    costPerInputToken?: number;
-    /** Cost per output token for usage tracking */
-    costPerOutputToken?: number;
     /** Default stop condition for subagents (default: stepCountIs(15)) */
     defaultStopWhen?: StopCondition<ToolSet>;
     /** Default callback for each step any subagent takes */
     defaultOnStepFinish?: (event: SubagentStepEvent) => void | Promise<void>;
+    /** Optional stream writer for real-time subagent activity (uses streamText instead of generateText) */
+    streamWriter?: UIMessageStreamWriter;
 }
 export declare function createTaskTool(config: TaskToolConfig): Tool;

package/dist/types.d.ts

@@ -7,6 +7,10 @@ export type ToolConfig = {
     allowedPaths?: string[];
     blockedCommands?: string[];
 };
+export type GrepToolConfig = ToolConfig & {
+    /** Use ripgrep (rg) instead of grep. Requires ripgrep to be installed. Default: false */
+    useRipgrep?: boolean;
+};
 export type WebSearchConfig = {
     apiKey: string;
 };
@@ -31,7 +35,7 @@ export type AgentConfig = {
         Write?: ToolConfig;
         Edit?: ToolConfig;
         Glob?: ToolConfig;
-        Grep?: ToolConfig;
+        Grep?: GrepToolConfig;
     };
     /** Include AskUser tool for user clarification */
     askUser?: AskUserConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bashkit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Agentic coding tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",

package/dist/tools/lsp.d.ts

@@ -1,94 +0,0 @@
-/**
- * A diagnostic (error/warning) from the language server.
- */
-export interface LspDiagnostic {
-    file: string;
-    line: number;
-    column: number;
-    endLine?: number;
-    endColumn?: number;
-    severity: "error" | "warning" | "info" | "hint";
-    message: string;
-    source?: string;
-    code?: string | number;
-}
-/**
- * A location in the codebase (for go-to-definition, references, etc.)
- */
-export interface LspLocation {
-    file: string;
-    line: number;
-    column: number;
-    endLine?: number;
-    endColumn?: number;
-    preview?: string;
-}
-/**
- * Hover information for a symbol.
- */
-export interface LspHoverInfo {
-    contents: string;
-    range?: {
-        startLine: number;
-        startColumn: number;
-        endLine: number;
-        endColumn: number;
-    };
-}
-/**
- * Interface that LSP providers must implement.
- * This abstracts over different LSP implementations (vscode, standalone servers, etc.)
- */
-export interface LspProvider {
-    /** Get diagnostics for a file or the entire workspace */
-    getDiagnostics(file?: string): Promise<LspDiagnostic[]>;
-    /** Go to definition of symbol at position */
-    getDefinition(file: string, line: number, column: number): Promise<LspLocation[]>;
-    /** Find all references to symbol at position */
-    getReferences(file: string, line: number, column: number): Promise<LspLocation[]>;
-    /** Get hover information for symbol at position */
-    getHover(file: string, line: number, column: number): Promise<LspHoverInfo | null>;
-    /** Get available actions at position (optional) */
-    getCodeActions?(file: string, line: number, column: number): Promise<Array<{
-        title: string;
-        kind?: string;
-    }>>;
-}
-export interface LspDiagnosticsOutput {
-    type: "diagnostics";
-    diagnostics: LspDiagnostic[];
-    counts: {
-        errors: number;
-        warnings: number;
-        info: number;
-        hints: number;
-    };
-}
-export interface LspDefinitionOutput {
-    type: "definition";
-    locations: LspLocation[];
-}
-export interface LspReferencesOutput {
-    type: "references";
-    locations: LspLocation[];
-    count: number;
-}
-export interface LspHoverOutput {
-    type: "hover";
-    info: LspHoverInfo | null;
-}
-export interface LspError {
-    error: string;
-}
-export type LspOutput = LspDiagnosticsOutput | LspDefinitionOutput | LspReferencesOutput | LspHoverOutput | LspError;
-/**
- * Creates an LSP tool for code intelligence operations.
- *
- * @param provider - An implementation of LspProvider that interfaces with language servers
- */
-export declare function createLspTool(provider: LspProvider): import("ai").Tool<{
-    action: "diagnostics" | "definition" | "references" | "hover";
-    file?: string | undefined;
-    line?: number | undefined;
-    column?: number | undefined;
-}, LspOutput>;