bashkit 0.1.0 → 0.1.1

package/AGENTS.md

@@ -24,7 +24,7 @@ Runs commands directly on the local machine. Use for development/testing only.
 import { createAgentTools, LocalSandbox } from "bashkit";
 
 const sandbox = new LocalSandbox("/tmp/workspace");
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 ```
 
 ### VercelSandbox (Production)
@@ -38,7 +38,7 @@ const sandbox = new VercelSandbox({
   runtime: "node22",
   resources: { vcpus: 2 },
 });
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 
 // Don't forget to cleanup
 await sandbox.destroy();
@@ -46,7 +46,7 @@ await sandbox.destroy();
 
 ## Available Tools
 
-### Sandbox-based Tools (from createAgentTools)
+### Default Tools (always included)
 
 | Tool | Purpose | Key Inputs |
 |------|---------|------------|
@@ -57,13 +57,23 @@ await sandbox.destroy();
 | `Glob` | Find files by pattern | `pattern`, `path?` |
 | `Grep` | Search file contents | `pattern`, `path?`, `output_mode?`, `-i?`, `-C?` |
 
+### Optional Tools (via config)
+
+| Tool | Purpose | Config Key |
+|------|---------|------------|
+| `AskUser` | Ask user clarifying questions | `askUser: { onQuestion? }` |
+| `EnterPlanMode` | Enter planning/exploration mode | `planMode: true` |
+| `ExitPlanMode` | Exit planning mode with a plan | `planMode: true` |
+| `Skill` | Execute skills | `skill: { skills }` |
+| `WebSearch` | Search the web | `webSearch: { apiKey }` |
+| `WebFetch` | Fetch URL and process with AI | `webFetch: { apiKey, model }` |
+
 ### Workflow Tools (created separately)
 
 | Tool | Purpose | Factory |
 |------|---------|---------|
 | `Task` | Spawn sub-agents | `createTaskTool({ model, tools, subagentTypes? })` |
 | `TodoWrite` | Track task progress | `createTodoWriteTool(state, config?, onUpdate?)` |
-| `ExitPlanMode` | Exit planning mode | `createExitPlanModeTool(config?, onPlanSubmit?)` |
 
 ### Web Tools (require `parallel-web` peer dependency)
 
@@ -84,7 +94,7 @@ import {
 } from "bashkit";
 
 const sandbox = new LocalSandbox("/tmp/workspace");
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 
 // Wrap model with prompt caching (recommended)
 const model = wrapLanguageModel({
@@ -273,7 +283,7 @@ import { anthropic } from "@ai-sdk/anthropic";
 
 const skills = await discoverSkills();
 const sandbox = new LocalSandbox("/tmp/workspace");
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 
 const result = await generateText({
   model: anthropic("claude-sonnet-4-20250514"),
@@ -363,7 +373,7 @@ const systemPrompt = `Save notes to: ${config.workspace.notes}
 ${skillsToXml(skills)}
 `;
 
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 ```
 
 ## Common Patterns
@@ -386,7 +396,7 @@ import {
 const sandbox = new LocalSandbox("/tmp/workspace");
 
 // 2. Create sandbox tools
-const sandboxTools = createAgentTools(sandbox);
+const { tools: sandboxTools } = createAgentTools(sandbox);
 
 // 3. Create model with caching
 const model = wrapLanguageModel({
@@ -424,7 +434,7 @@ await sandbox.destroy();
 Restrict tools with configuration:
 
 ```typescript
-const tools = createAgentTools(sandbox, {
+const { tools } = createAgentTools(sandbox, {
   tools: {
     Bash: {
       enabled: true,

package/README.md

@@ -43,7 +43,7 @@ import { generateText, stepCountIs } from 'ai';
 const sandbox = createLocalSandbox({ cwd: '/tmp/workspace' });
 
 // Create tools bound to the sandbox
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 
 // Use with Vercel AI SDK
 const result = await generateText({
@@ -74,7 +74,7 @@ const sandbox = createVercelSandbox({
   resources: { vcpus: 2 },
 });
 
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 
 const result = streamText({
   model: anthropic('claude-sonnet-4-5'),
@@ -89,7 +89,7 @@ await sandbox.destroy();
 
 ## Available Tools
 
-### Sandbox-based Tools (from `createAgentTools`)
+### Default Tools (always included)
 
 | Tool | Purpose | Key Inputs |
 |------|---------|------------|
@@ -100,13 +100,23 @@ await sandbox.destroy();
 | `Glob` | Find files by pattern | `pattern`, `path?` |
 | `Grep` | Search file contents | `pattern`, `path?`, `output_mode?`, `-i?`, `-C?` |
 
+### Optional Tools (via config)
+
+| Tool | Purpose | Config Key |
+|------|---------|------------|
+| `AskUser` | Ask user clarifying questions | `askUser: { onQuestion? }` |
+| `EnterPlanMode` | Enter planning/exploration mode | `planMode: true` |
+| `ExitPlanMode` | Exit planning mode with a plan | `planMode: true` |
+| `Skill` | Execute skills | `skill: { skills }` |
+| `WebSearch` | Search the web | `webSearch: { apiKey }` |
+| `WebFetch` | Fetch URL and process with AI | `webFetch: { apiKey, model }` |
+
 ### Workflow Tools (created separately)
 
 | Tool | Purpose | Factory |
 |------|---------|---------|
 | `Task` | Spawn sub-agents | `createTaskTool({ model, tools, subagentTypes? })` |
 | `TodoWrite` | Track task progress | `createTodoWriteTool(state, config?, onUpdate?)` |
-| `ExitPlanMode` | Exit planning mode | `createExitPlanModeTool(config?, onPlanSubmit?)` |
 
 ### Web Tools (require `parallel-web` peer dependency)
 
@@ -154,10 +164,30 @@ const sandbox = createE2BSandbox({
 
 ## Configuration
 
-You can configure tools with security restrictions and limits:
+You can configure tools with security restrictions and limits, and enable optional tools:
 
 ```typescript
-const tools = createAgentTools(sandbox, {
+const { tools, planModeState } = createAgentTools(sandbox, {
+  // Enable optional tools
+  askUser: {
+    onQuestion: async (question) => {
+      // Return user's answer, or undefined to return awaiting_response
+      return await promptUser(question);
+    },
+  },
+  planMode: true, // Enables EnterPlanMode and ExitPlanMode
+  skill: {
+    skills: discoveredSkills, // From discoverSkills()
+  },
+  webSearch: {
+    apiKey: process.env.PARALLEL_API_KEY,
+  },
+  webFetch: {
+    apiKey: process.env.PARALLEL_API_KEY,
+    model: anthropic('claude-haiku-4'),
+  },
+
+  // Tool-specific config
   tools: {
     Bash: {
       timeout: 30000,
@@ -171,13 +201,6 @@ const tools = createAgentTools(sandbox, {
       maxFileSize: 1_000_000, // 1MB limit
     },
   },
-  webSearch: {
-    apiKey: process.env.PARALLEL_API_KEY,
-  },
-  webFetch: {
-    apiKey: process.env.PARALLEL_API_KEY,
-    model: anthropic('claude-haiku-4'),
-  },
 });
 ```
 
@@ -335,7 +358,7 @@ import { discoverSkills, skillsToXml, createAgentTools, createLocalSandbox } fro
 
 const skills = await discoverSkills();
 const sandbox = createLocalSandbox({ cwd: '/tmp/workspace' });
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 
 const result = await generateText({
   model: anthropic('claude-sonnet-4-5'),
@@ -504,7 +527,7 @@ ${skillsToXml(skills)}
 `;
 
 // Create tools and run
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 
 const result = await generateText({
   model: anthropic('claude-sonnet-4-5'),
@@ -571,7 +594,7 @@ class DockerSandbox implements Sandbox {
 }
 
 const sandbox = new DockerSandbox();
-const tools = createAgentTools(sandbox);
+const { tools } = createAgentTools(sandbox);
 ```
 
 ## Architecture
@@ -641,7 +664,13 @@ Creates a set of agent tools bound to a sandbox instance.
 
 - `createTaskTool(config)` - Spawn sub-agents for complex tasks
 - `createTodoWriteTool(state, config?, onUpdate?)` - Track task progress
-- `createExitPlanModeTool(config?, onPlanSubmit?)` - Exit planning mode
+
+### Optional Tools (also available via config)
+
+- `createAskUserTool(onQuestion?)` - Ask user for clarification
+- `createEnterPlanModeTool(state)` - Enter planning/exploration mode
+- `createExitPlanModeTool(state, onPlanSubmit?)` - Exit planning mode with a plan
+- `createSkillTool(skills)` - Execute loaded skills
 
 ### Utilities
 

package/dist/cli/init.js

@@ -54,7 +54,7 @@ export const config: AgentConfig = {${webTools ? `
 ` : ""}};
 
 // Create tools
-export const tools = createAgentTools(sandbox${webTools ? ", config" : ""});
+export const { tools } = createAgentTools(sandbox${webTools ? ", config" : ""});
 `;
   const configPath = join(process.cwd(), "bashkit.config.ts");
   if (existsSync(configPath)) {
@@ -141,7 +141,7 @@ async function init() {
         stdio: "inherit"
       });
       s.stop("Dependencies installed ✓");
-    } catch (error) {
+    } catch {
       s.stop("Installation failed ✗");
       console.error(`
 ❌ Failed to install dependencies`);

package/dist/index.d.ts

@@ -2,9 +2,9 @@ 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 { BashError, BashOutput, EditError, EditOutput, ExitPlanModeError, ExitPlanModeOutput, GlobError, GlobOutput, GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, GrepMatch, GrepOutput, ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, SubagentStepEvent, SubagentTypeConfig, TaskError, TaskOutput, TaskToolConfig, TodoItem, TodoState, TodoWriteError, TodoWriteOutput, WebFetchError, WebFetchOutput, WebFetchToolConfig, WebSearchError, WebSearchOutput, WebSearchResult, WebSearchToolConfig, WriteError, WriteOutput, } from "./tools";
-export { createAgentTools, createBashTool, createEditTool, createExitPlanModeTool, createGlobTool, createGrepTool, createReadTool, createTaskTool, createTodoWriteTool, createWebFetchTool, createWebSearchTool, createWriteTool, } from "./tools";
-export type { AgentConfig, ToolConfig, WebFetchConfig, WebSearchConfig, } from "./types";
+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 { 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";
 export type { CompactConversationConfig, CompactConversationResult, CompactConversationState, ContextMetrics, ContextStatus, ContextStatusConfig, ContextStatusLevel, ModelContextLimit, PruneMessagesConfig, } from "./utils";
 export { compactConversation, contextNeedsAttention, contextNeedsCompaction, createCompactConfig, estimateMessagesTokens, estimateMessageTokens, estimateTokens, getContextStatus, MODEL_CONTEXT_LIMITS, pruneMessagesByTokens, } from "./utils";

package/dist/index.js

@@ -358,14 +358,59 @@ var DEFAULT_CONFIG = {
   }
 };
 
-// src/tools/bash.ts
+// src/tools/ask-user.ts
 import { tool, zodSchema } from "ai";
 import { z } from "zod";
-var bashInputSchema = z.object({
-  command: z.string().describe("The command to execute"),
-  timeout: z.number().optional().describe("Optional timeout in milliseconds (max 600000)"),
-  description: z.string().optional().describe("Clear, concise description of what this command does in 5-10 words"),
-  run_in_background: z.boolean().optional().describe("Set to true to run this command in the background")
+var askUserInputSchema = z.object({
+  question: z.string().describe("The question to ask the user. Be specific and concise.")
+});
+var ASK_USER_DESCRIPTION = `Ask the user a clarifying question when you need more information to proceed.
+
+**When to use:**
+- You need clarification on ambiguous requirements
+- Multiple valid approaches exist and user preference matters
+- You're about to make a decision with significant consequences
+- Required information is missing from the context
+
+**When NOT to use:**
+- You can make a reasonable assumption
+- 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) {
+  return tool({
+    description: ASK_USER_DESCRIPTION,
+    inputSchema: zodSchema(askUserInputSchema),
+    execute: async ({
+      question
+    }) => {
+      try {
+        if (onQuestion) {
+          const answer = await onQuestion(question);
+          return { answer };
+        }
+        return {
+          question,
+          awaiting_response: true
+        };
+      } catch (error) {
+        return {
+          error: error instanceof Error ? error.message : "Unknown error"
+        };
+      }
+    }
+  });
+}
+
+// src/tools/bash.ts
+import { tool as tool2, zodSchema as zodSchema2 } from "ai";
+import { z as z2 } from "zod";
+var bashInputSchema = z2.object({
+  command: z2.string().describe("The command to execute"),
+  timeout: z2.number().optional().describe("Optional timeout in milliseconds (max 600000)"),
+  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.
 
@@ -379,9 +424,9 @@ var BASH_DESCRIPTION = `Executes bash commands in a persistent shell session wit
 function createBashTool(sandbox, config) {
   const maxOutputLength = config?.maxOutputLength ?? 30000;
   const defaultTimeout = config?.timeout ?? 120000;
-  return tool({
+  return tool2({
     description: BASH_DESCRIPTION,
-    inputSchema: zodSchema(bashInputSchema),
+    inputSchema: zodSchema2(bashInputSchema),
     execute: async ({
       command,
       timeout,
@@ -429,18 +474,18 @@ function createBashTool(sandbox, config) {
 }
 
 // src/tools/edit.ts
-import { tool as tool2, zodSchema as zodSchema2 } from "ai";
-import { z as z2 } from "zod";
-var editInputSchema = z2.object({
-  file_path: z2.string().describe("The absolute path to the file to modify"),
-  old_string: z2.string().describe("The text to replace"),
-  new_string: z2.string().describe("The text to replace it with (must be different from old_string)"),
-  replace_all: z2.boolean().optional().describe("Replace all occurrences of old_string (default false)")
+import { tool as tool3, zodSchema as zodSchema3 } from "ai";
+import { z as z3 } from "zod";
+var editInputSchema = z3.object({
+  file_path: z3.string().describe("The absolute path to the file to modify"),
+  old_string: z3.string().describe("The text to replace"),
+  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)")
 });
 function createEditTool(sandbox, config) {
-  return tool2({
+  return tool3({
     description: "Performs exact string replacements in files.",
-    inputSchema: zodSchema2(editInputSchema),
+    inputSchema: zodSchema3(editInputSchema),
     execute: async ({
       file_path,
       old_string,
@@ -495,17 +540,104 @@ function createEditTool(sandbox, config) {
   });
 }
 
+// src/tools/enter-plan-mode.ts
+import { tool as tool4, zodSchema as zodSchema4 } from "ai";
+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.
+
+**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
+
+**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
+
+**When NOT to use:**
+- Simple, well-defined tasks
+- You already understand the codebase and approach
+- User wants immediate execution`;
+function createEnterPlanModeTool(state, onEnter) {
+  return tool4({
+    description: ENTER_PLAN_MODE_DESCRIPTION,
+    inputSchema: zodSchema4(enterPlanModeInputSchema),
+    execute: async ({
+      reason
+    }) => {
+      try {
+        if (state.isActive) {
+          return {
+            error: "Already in planning mode. Use ExitPlanMode to exit."
+          };
+        }
+        state.isActive = true;
+        state.enteredAt = new Date;
+        state.reason = reason;
+        if (onEnter) {
+          await onEnter(reason);
+        }
+        return {
+          message: `Entered planning mode: ${reason}. Use Read, Grep, and Glob to explore. Call ExitPlanMode when ready with a plan.`,
+          mode: "planning"
+        };
+      } catch (error) {
+        return {
+          error: error instanceof Error ? error.message : "Unknown error"
+        };
+      }
+    }
+  });
+}
+
+// src/tools/exit-plan-mode.ts
+import { tool as tool5, zodSchema as zodSchema5 } from "ai";
+import { z as z5 } from "zod";
+var exitPlanModeInputSchema = z5.object({
+  plan: z5.string().describe("The plan to present to the user for approval")
+});
+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.",
+    inputSchema: zodSchema5(exitPlanModeInputSchema),
+    execute: async ({
+      plan
+    }) => {
+      try {
+        let approved;
+        if (onPlanSubmit) {
+          approved = await onPlanSubmit(plan);
+        }
+        return {
+          message: approved ? "Plan approved, proceeding with execution" : "Plan submitted for review",
+          approved
+        };
+      } catch (error) {
+        return {
+          error: error instanceof Error ? error.message : "Unknown error"
+        };
+      }
+    }
+  });
+}
+
 // src/tools/glob.ts
-import { tool as tool3, zodSchema as zodSchema3 } from "ai";
-import { z as z3 } from "zod";
-var globInputSchema = z3.object({
-  pattern: z3.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js", "*.md")'),
-  path: z3.string().optional().describe("Directory to search in (defaults to working directory)")
+import { tool as tool6, zodSchema as zodSchema6 } from "ai";
+import { z as z6 } from "zod";
+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)")
 });
 function createGlobTool(sandbox, config) {
-  return tool3({
+  return tool6({
     description: "Search for files matching a glob pattern. Returns file paths sorted by modification time. Use this instead of `find` command.",
-    inputSchema: zodSchema3(globInputSchema),
+    inputSchema: zodSchema6(globInputSchema),
     execute: async ({
       pattern,
       path
@@ -539,26 +671,26 @@ function createGlobTool(sandbox, config) {
 }
 
 // src/tools/grep.ts
-import { tool as tool4, zodSchema as zodSchema4 } from "ai";
-import { z as z4 } from "zod";
-var grepInputSchema = z4.object({
-  pattern: z4.string().describe("The regular expression pattern to search for"),
-  path: z4.string().optional().describe("File or directory to search in (defaults to cwd)"),
-  glob: z4.string().optional().describe('Glob pattern to filter files (e.g. "*.js")'),
-  type: z4.string().optional().describe('File type to search (e.g. "js", "py", "rust")'),
-  output_mode: z4.enum(["content", "files_with_matches", "count"]).optional().describe('Output mode: "content", "files_with_matches", or "count"'),
-  "-i": z4.boolean().optional().describe("Case insensitive search"),
-  "-n": z4.boolean().optional().describe("Show line numbers (for content mode)"),
-  "-B": z4.number().optional().describe("Lines to show before each match"),
-  "-A": z4.number().optional().describe("Lines to show after each match"),
-  "-C": z4.number().optional().describe("Lines to show before and after each match"),
-  head_limit: z4.number().optional().describe("Limit output to first N lines/entries"),
-  multiline: z4.boolean().optional().describe("Enable multiline mode")
+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"),
+  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")'),
+  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"'),
+  "-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")
 });
 function createGrepTool(sandbox, config) {
-  return tool4({
+  return tool7({
     description: "Powerful search tool built on ripgrep with regex support. Use this instead of the grep command.",
-    inputSchema: zodSchema4(grepInputSchema),
+    inputSchema: zodSchema7(grepInputSchema),
     execute: async (input) => {
       const {
         pattern,
@@ -668,17 +800,17 @@ function createGrepTool(sandbox, config) {
 }
 
 // src/tools/read.ts
-import { tool as tool5, zodSchema as zodSchema5 } from "ai";
-import { z as z5 } from "zod";
-var readInputSchema = z5.object({
-  file_path: z5.string().describe("Absolute path to file or directory"),
-  offset: z5.number().optional().describe("Line number to start reading from (1-indexed)"),
-  limit: z5.number().optional().describe("Maximum number of lines to read")
+import { tool as tool8, zodSchema as zodSchema8 } from "ai";
+import { z as z8 } from "zod";
+var readInputSchema = z8.object({
+  file_path: z8.string().describe("Absolute path to file or directory"),
+  offset: z8.number().optional().describe("Line number to start reading from (1-indexed)"),
+  limit: z8.number().optional().describe("Maximum number of lines to read")
 });
 function createReadTool(sandbox, config) {
-  return tool5({
+  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.",
-    inputSchema: zodSchema5(readInputSchema),
+    inputSchema: zodSchema8(readInputSchema),
     execute: async ({
       file_path,
       offset,
@@ -760,20 +892,91 @@ function createReadTool(sandbox, config) {
   });
 }
 
+// src/tools/skill.ts
+import { tool as tool9, zodSchema as zodSchema9 } from "ai";
+import { z as z9 } from "zod";
+var skillInputSchema = z9.object({
+  name: z9.string().describe("The name of the skill to activate (from available skills list)")
+});
+var SKILL_DESCRIPTION = `Activate a skill to get specialized instructions for a task.
+
+**How skills work:**
+1. Skills are pre-loaded at startup (only metadata: name, description, path)
+2. Calling this tool loads the full skill instructions from SKILL.md
+3. Follow the returned instructions to complete the task
+4. Some skills restrict which tools you can use (allowed_tools)
+
+**When to use:**
+- A task matches a skill's description
+- You need specialized knowledge for a domain (e.g., PDF processing, web research)
+- The skill provides step-by-step guidance you should follow
+
+**Available skills are listed in the system prompt.**`;
+function createSkillTool(config) {
+  const { skills, sandbox, onActivate } = config;
+  return tool9({
+    description: SKILL_DESCRIPTION,
+    inputSchema: zodSchema9(skillInputSchema),
+    execute: async ({
+      name
+    }) => {
+      try {
+        const skill = skills[name];
+        if (!skill) {
+          const available = Object.keys(skills);
+          if (available.length === 0) {
+            return { error: "No skills are available." };
+          }
+          return {
+            error: `Skill '${name}' not found. Available skills: ${available.join(", ")}`
+          };
+        }
+        let instructions;
+        if (!sandbox) {
+          return {
+            error: `Cannot load skill '${name}': no sandbox provided to read ${skill.path}`
+          };
+        }
+        const content = await sandbox.readFile(skill.path);
+        const frontmatterEnd = content.indexOf(`
+---`, 4);
+        if (frontmatterEnd !== -1) {
+          instructions = content.slice(frontmatterEnd + 4).trim();
+        } else {
+          instructions = content;
+        }
+        if (onActivate) {
+          await onActivate(skill, instructions);
+        }
+        return {
+          name: skill.name,
+          instructions,
+          allowed_tools: skill.allowedTools,
+          message: skill.allowedTools ? `Skill '${name}' activated. Restricted to tools: ${skill.allowedTools.join(", ")}` : `Skill '${name}' activated. Follow the instructions below.`
+        };
+      } catch (error) {
+        return {
+          error: error instanceof Error ? error.message : "Unknown error"
+        };
+      }
+    }
+  });
+}
+
 // src/tools/web-fetch.ts
-import { generateText, tool as tool6, zodSchema as zodSchema6 } from "ai";
+import { generateText, tool as tool10, zodSchema as zodSchema10 } from "ai";
 import Parallel from "parallel-web";
-import { z as z6 } from "zod";
-var webFetchInputSchema = z6.object({
-  url: z6.string().describe("The URL to fetch content from"),
-  prompt: z6.string().describe("The prompt to run on the fetched content")
+import { z as z10 } from "zod";
+var webFetchInputSchema = z10.object({
+  url: z10.string().describe("The URL to fetch content from"),
+  prompt: z10.string().describe("The prompt to run on the fetched content")
 });
 var RETRYABLE_CODES = [408, 429, 500, 502, 503];
 function createWebFetchTool(config) {
   const { apiKey, model } = config;
-  return tool6({
+  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.",
-    inputSchema: zodSchema6(webFetchInputSchema),
+    inputSchema: zodSchema10(webFetchInputSchema),
     execute: async (input) => {
       const { url, prompt } = input;
       try {
@@ -833,20 +1036,20 @@ ${content}`
 }
 
 // src/tools/web-search.ts
-import { tool as tool7, zodSchema as zodSchema7 } from "ai";
+import { tool as tool11, zodSchema as zodSchema11 } from "ai";
 import Parallel2 from "parallel-web";
-import { z as z7 } from "zod";
-var webSearchInputSchema = z7.object({
-  query: z7.string().describe("The search query to use"),
-  allowed_domains: z7.array(z7.string()).optional().describe("Only include results from these domains"),
-  blocked_domains: z7.array(z7.string()).optional().describe("Never include results from these domains")
+import { z as z11 } from "zod";
+var webSearchInputSchema = z11.object({
+  query: z11.string().describe("The search query to use"),
+  allowed_domains: z11.array(z11.string()).optional().describe("Only include results from these domains"),
+  blocked_domains: z11.array(z11.string()).optional().describe("Never include results from these domains")
 });
 var RETRYABLE_CODES2 = [408, 429, 500, 502, 503];
 function createWebSearchTool(config) {
   const { apiKey } = config;
-  return tool7({
+  return tool11({
     description: "Searches the web and returns formatted results. Use this to find current information, documentation, articles, and more.",
-    inputSchema: zodSchema7(webSearchInputSchema),
+    inputSchema: zodSchema11(webSearchInputSchema),
     execute: async (input) => {
       const { query, allowed_domains, blocked_domains } = input;
       try {
@@ -892,16 +1095,16 @@ function createWebSearchTool(config) {
 }
 
 // src/tools/write.ts
-import { tool as tool8, zodSchema as zodSchema8 } from "ai";
-import { z as z8 } from "zod";
-var writeInputSchema = z8.object({
-  file_path: z8.string().describe("Path to the file to write"),
-  content: z8.string().describe("Content to write to the file")
+import { tool as tool12, zodSchema as zodSchema12 } from "ai";
+import { z as z12 } from "zod";
+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")
 });
 function createWriteTool(sandbox, config) {
-  return tool8({
+  return tool12({
     description: "Write content to a file. Creates the file if it does not exist, overwrites if it does.",
-    inputSchema: zodSchema8(writeInputSchema),
+    inputSchema: zodSchema12(writeInputSchema),
     execute: async ({
       file_path,
       content
@@ -933,48 +1136,18 @@ function createWriteTool(sandbox, config) {
     }
   });
 }
-// src/tools/exit-plan-mode.ts
-import { tool as tool9, zodSchema as zodSchema9 } from "ai";
-import { z as z9 } from "zod";
-var exitPlanModeInputSchema = z9.object({
-  plan: z9.string().describe("The plan to present to the user for approval")
-});
-function createExitPlanModeTool(config, onPlanSubmit) {
-  return tool9({
-    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.",
-    inputSchema: zodSchema9(exitPlanModeInputSchema),
-    execute: async ({
-      plan
-    }) => {
-      try {
-        let approved;
-        if (onPlanSubmit) {
-          approved = await onPlanSubmit(plan);
-        }
-        return {
-          message: approved ? "Plan approved, proceeding with execution" : "Plan submitted for review",
-          approved
-        };
-      } catch (error) {
-        return {
-          error: error instanceof Error ? error.message : "Unknown error"
-        };
-      }
-    }
-  });
-}
 // src/tools/task.ts
 import {
   generateText as generateText2,
   stepCountIs,
-  tool as tool10,
-  zodSchema as zodSchema10
+  tool as tool13,
+  zodSchema as zodSchema13
 } from "ai";
-import { z as z10 } from "zod";
-var taskInputSchema = z10.object({
-  description: z10.string().describe("A short (3-5 word) description of the task"),
-  prompt: z10.string().describe("The task for the agent to perform"),
-  subagent_type: z10.string().describe("The type of specialized agent to use for this task")
+import { z as z13 } from "zod";
+var taskInputSchema = z13.object({
+  description: z13.string().describe("A short (3-5 word) description of the task"),
+  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")
 });
 function filterTools(allTools, allowedTools) {
   if (!allowedTools)
@@ -997,9 +1170,9 @@ function createTaskTool(config) {
     defaultStopWhen,
     defaultOnStepFinish
   } = config;
-  return tool10({
+  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.",
-    inputSchema: zodSchema10(taskInputSchema),
+    inputSchema: zodSchema13(taskInputSchema),
     execute: async ({
       description,
       prompt,
@@ -1051,19 +1224,19 @@ function createTaskTool(config) {
   });
 }
 // src/tools/todo-write.ts
-import { tool as tool11, zodSchema as zodSchema11 } from "ai";
-import { z as z11 } from "zod";
-var todoWriteInputSchema = z11.object({
-  todos: z11.array(z11.object({
-    content: z11.string().describe("The task description"),
-    status: z11.enum(["pending", "in_progress", "completed"]).describe("The task status"),
-    activeForm: z11.string().describe("Active form of the task description")
+import { tool as tool14, zodSchema as zodSchema14 } from "ai";
+import { z as z14 } from "zod";
+var todoWriteInputSchema = z14.object({
+  todos: z14.array(z14.object({
+    content: z14.string().describe("The task description"),
+    status: z14.enum(["pending", "in_progress", "completed"]).describe("The task status"),
+    activeForm: z14.string().describe("Active form of the task description")
   })).describe("The updated todo list")
 });
 function createTodoWriteTool(state, config, onUpdate) {
-  return tool11({
+  return tool14({
     description: "Creates and manages a structured task list for tracking progress. Use this to plan complex tasks and track completion.",
-    inputSchema: zodSchema11(todoWriteInputSchema),
+    inputSchema: zodSchema14(todoWriteInputSchema),
     execute: async ({
       todos
     }) => {
@@ -1105,13 +1278,29 @@ function createAgentTools(sandbox, config) {
     Glob: createGlobTool(sandbox, toolsConfig.Glob),
     Grep: createGrepTool(sandbox, toolsConfig.Grep)
   };
+  let planModeState;
+  if (config?.askUser) {
+    tools.AskUser = createAskUserTool(config.askUser.onQuestion);
+  }
+  if (config?.planMode) {
+    planModeState = { isActive: false };
+    tools.EnterPlanMode = createEnterPlanModeTool(planModeState);
+    tools.ExitPlanMode = createExitPlanModeTool();
+  }
+  if (config?.skill) {
+    tools.Skill = createSkillTool({
+      skills: config.skill.skills,
+      sandbox,
+      onActivate: config.skill.onActivate
+    });
+  }
   if (config?.webSearch) {
     tools.WebSearch = createWebSearchTool(config.webSearch);
   }
   if (config?.webFetch) {
     tools.WebFetch = createWebFetchTool(config.webFetch);
   }
-  return tools;
+  return { tools, planModeState };
 }
 // src/utils/compact-conversation.ts
 import { generateText as generateText3 } from "ai";
@@ -1786,15 +1975,18 @@ export {
   createVercelSandbox,
   createTodoWriteTool,
   createTaskTool,
+  createSkillTool,
   createReadTool,
   createLocalSandbox,
   createGrepTool,
   createGlobTool,
   createExitPlanModeTool,
+  createEnterPlanModeTool,
   createEditTool,
   createE2BSandbox,
   createCompactConfig,
   createBashTool,
+  createAskUserTool,
   createAgentTools,
   contextNeedsCompaction,
   contextNeedsAttention,

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

@@ -0,0 +1,23 @@
+export interface AskUserOutput {
+    question: string;
+    awaiting_response: true;
+}
+export interface AskUserError {
+    error: string;
+}
+export type AskUserResponseHandler = (question: string) => Promise<string> | string;
+/**
+ * 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
+ *
+ * @param onQuestion - Optional callback to handle the question and return an answer
+ */
+export declare function createAskUserTool(onQuestion?: AskUserResponseHandler): import("ai").Tool<{
+    question: string;
+}, AskUserOutput | AskUserError | {
+    answer: string;
+}>;

package/dist/tools/enter-plan-mode.d.ts

@@ -0,0 +1,22 @@
+export interface PlanModeState {
+    isActive: boolean;
+    enteredAt?: Date;
+    reason?: string;
+}
+export interface EnterPlanModeOutput {
+    message: string;
+    mode: "planning";
+}
+export interface EnterPlanModeError {
+    error: string;
+}
+/**
+ * Creates a tool for entering planning mode.
+ * Works in conjunction with ExitPlanMode for plan-then-execute workflows.
+ *
+ * @param state - Shared state object to track planning mode
+ * @param onEnter - Optional callback when entering planning mode
+ */
+export declare function createEnterPlanModeTool(state: PlanModeState, onEnter?: (reason: string) => void | Promise<void>): import("ai").Tool<{
+    reason: string;
+}, EnterPlanModeOutput | EnterPlanModeError>;

package/dist/tools/index.d.ts

@@ -1,30 +1,60 @@
 import type { ToolSet } from "ai";
 import type { Sandbox } from "../sandbox/interface";
 import type { AgentConfig } from "../types";
+import { type PlanModeState } from "./enter-plan-mode";
 /**
- * Creates all sandbox-based agent tools for AI SDK's generateText/streamText.
- * Returns an object with Bash, Read, Write, Edit, Glob, Grep tools.
- * Optionally includes WebSearch and WebFetch if configured.
+ * Result from createAgentTools including tools and optional shared state.
+ */
+export interface AgentToolsResult {
+    /** All configured tools for use with generateText/streamText */
+    tools: ToolSet;
+    /** Shared plan mode state (only present when planMode is enabled) */
+    planModeState?: PlanModeState;
+}
+/**
+ * Creates agent tools for AI SDK's generateText/streamText.
+ *
+ * **Default tools (always included):**
+ * - Bash, Read, Write, Edit, Glob, Grep (sandbox operations)
+ *
+ * **Optional tools (via config):**
+ * - `askUser` — AskUser tool for clarifying questions
+ * - `planMode` — EnterPlanMode, ExitPlanMode for interactive planning
+ * - `skill` — Skill tool for skill execution
+ * - `webSearch` — WebSearch tool
+ * - `webFetch` — WebFetch tool
  *
  * @param sandbox - The sandbox to execute commands in
- * @param config - Optional configuration for individual tools and web tools
+ * @param config - Optional configuration for tools
+ * @returns Object with tools and optional planModeState
  *
  * @example
- * // Basic sandbox tools only
- * const tools = createAgentTools(sandbox);
+ * // Basic usage (lean default for background agents)
+ * const { tools } = createAgentTools(sandbox);
+ *
+ * @example
+ * // Interactive agent with plan mode
+ * const { tools, planModeState } = createAgentTools(sandbox, {
+ *   planMode: true,
+ *   askUser: { onQuestion: async (q) => await promptUser(q) },
+ * });
  *
  * @example
- * // With web tools included
- * const tools = createAgentTools(sandbox, {
+ * // With web and skill tools
+ * const { tools } = createAgentTools(sandbox, {
  *   webSearch: { apiKey: process.env.PARALLEL_API_KEY },
- *   webFetch: { apiKey: process.env.PARALLEL_API_KEY, model: haiku },
+ *   skill: { skills: discoveredSkills },
  * });
  */
-export declare function createAgentTools(sandbox: Sandbox, config?: AgentConfig): ToolSet;
+export declare function createAgentTools(sandbox: Sandbox, config?: AgentConfig): AgentToolsResult;
+export type { AskUserError, AskUserOutput, AskUserResponseHandler, } from "./ask-user";
+export { createAskUserTool } from "./ask-user";
 export type { BashError, BashOutput } from "./bash";
 export { createBashTool } from "./bash";
 export type { EditError, EditOutput } from "./edit";
 export { createEditTool } from "./edit";
+export type { EnterPlanModeError, EnterPlanModeOutput, PlanModeState, } from "./enter-plan-mode";
+export { createEnterPlanModeTool } from "./enter-plan-mode";
 export type { ExitPlanModeError, ExitPlanModeOutput } from "./exit-plan-mode";
 export { createExitPlanModeTool } from "./exit-plan-mode";
 export type { GlobError, GlobOutput } from "./glob";
@@ -33,6 +63,8 @@ export type { GrepContentOutput, GrepCountOutput, GrepError, GrepFilesOutput, Gr
 export { createGrepTool } from "./grep";
 export type { ReadDirectoryOutput, ReadError, ReadOutput, ReadTextOutput, } from "./read";
 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 { createTaskTool } from "./task";
 export type { TodoItem, TodoState, TodoWriteError, TodoWriteOutput, } from "./todo-write";

package/dist/tools/lsp.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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>;

package/dist/tools/skill.d.ts

@@ -0,0 +1,27 @@
+import type { Sandbox } from "../sandbox/interface";
+import type { SkillMetadata } from "../skills/types";
+export interface SkillOutput {
+    name: string;
+    instructions: string;
+    allowed_tools?: string[];
+    message: string;
+}
+export interface SkillError {
+    error: string;
+}
+export interface SkillToolConfig {
+    /** Map of skill name to metadata (from discoverSkills or setupAgentEnvironment) */
+    skills: Record<string, SkillMetadata>;
+    /** Sandbox for reading skill files (optional if skills have embedded content) */
+    sandbox?: Sandbox;
+    /** Callback when a skill is activated */
+    onActivate?: (skill: SkillMetadata, instructions: string) => void | Promise<void>;
+}
+/**
+ * Creates a tool for activating and loading skills.
+ *
+ * @param config - Configuration with available skills and optional sandbox
+ */
+export declare function createSkillTool(config: SkillToolConfig): import("ai").Tool<{
+    name: string;
+}, SkillOutput | SkillError>;

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { LanguageModel } from "ai";
+import type { SkillMetadata } from "./skills/types";
 export type ToolConfig = {
     timeout?: number;
     maxFileSize?: number;
@@ -13,6 +14,16 @@ export type WebFetchConfig = {
     apiKey: string;
     model: LanguageModel;
 };
+export type AskUserConfig = {
+    /** Callback to handle questions and return answers */
+    onQuestion?: (question: string) => Promise<string> | string;
+};
+export type SkillConfig = {
+    /** Map of skill name to metadata */
+    skills: Record<string, SkillMetadata>;
+    /** Callback when a skill is activated */
+    onActivate?: (skill: SkillMetadata, instructions: string) => void | Promise<void>;
+};
 export type AgentConfig = {
     tools?: {
         Bash?: ToolConfig;
@@ -22,6 +33,12 @@ export type AgentConfig = {
         Glob?: ToolConfig;
         Grep?: ToolConfig;
     };
+    /** Include AskUser tool for user clarification */
+    askUser?: AskUserConfig;
+    /** Include EnterPlanMode and ExitPlanMode tools for interactive planning */
+    planMode?: boolean;
+    /** Include Skill tool with this config */
+    skill?: SkillConfig;
     /** Include WebSearch tool with this config */
     webSearch?: WebSearchConfig;
     /** Include WebFetch tool with this config */

package/package.json

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