Refactor AskUser tool to deferred client-rendered model (#25)

Replace server-side onQuestion/onStructuredQuestions handlers with a
deferred tool that emits structured questions for the client to render.
Each question now has a stable `id` for deterministic answer mapping.
Simplifies config from `askUser: { onQuestion }` to `askUser: true`.
Bumps version to 0.6.0 (breaking change).

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jbreite

AGENTS.md

@@ -126,7 +126,7 @@ See also `CLAUDE.md` for development workflow and conventions.
 
 | Tool | Purpose | Config Key |
 |------|---------|------------|
-| `AskUser` | Ask user clarifying questions | `askUser: { onQuestion? }` |
+| `AskUser` | Ask user clarifying questions | `askUser: true` |
 | `EnterPlanMode` | Enter planning/exploration mode | `planMode: true` |
 | `ExitPlanMode` | Exit planning mode with a plan | `planMode: true` |
 | `Skill` | Execute skills | `skill: { skills }` |
@@ -656,4 +656,3 @@ const cachedTool = cached(myTool, "MyTool", {
   store: new LRUCacheStore(500),  // Max 500 entries
 });
 ```
-

README.md

@@ -133,7 +133,7 @@ await sandbox.destroy();
 
 | Tool | Purpose | Config Key |
 |------|---------|------------|
-| `AskUser` | Ask user clarifying questions | `askUser: { onQuestion? }` |
+| `AskUser` | Ask user clarifying questions | `askUser: true` |
 | `EnterPlanMode` | Enter planning/exploration mode | `planMode: true` |
 | `ExitPlanMode` | Exit planning mode with a plan | `planMode: true` |
 | `Skill` | Execute skills | `skill: { skills }` |
@@ -221,12 +221,7 @@ You can configure tools with security restrictions and limits, and enable option
 ```typescript
 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);
-    },
-  },
+  askUser: true,
   planMode: true, // Enables EnterPlanMode and ExitPlanMode
   skill: {
     skills: discoveredSkills, // From discoverSkills()
@@ -917,7 +912,7 @@ Creates a set of agent tools bound to a sandbox instance.
 
 ### Optional Tools (also available via config)
 
-- `createAskUserTool(onQuestion?)` - Ask user for clarification
+- `createAskUserTool(config?)` - Emit a deferred AskUser tool call for the client
 - `createEnterPlanModeTool(state)` - Enter planning/exploration mode
 - `createExitPlanModeTool(state, onPlanSubmit?)` - Exit planning mode with a plan
 - `createSkillTool(skills)` - Execute loaded skills

package.json

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

src/index.ts

@@ -38,11 +38,12 @@ export type {
   // Result type from createAgentTools
   AgentToolsResult,
   // AskUser tool
-  AskUserError,
+  AskUserAnswers,
+  AskUserInput,
   AskUserOutput,
-  AskUserResponseHandler,
-  QuestionOption,
-  StructuredQuestion,
+  AskUserQuestion,
+  AskUserQuestionOption,
+  AskUserToolConfig,
   // Sandbox tools
   BashError,
   BashOutput,

src/tools/AGENTS.md

@@ -12,7 +12,7 @@ The tools module implements all 15 AI agent tools in BashKit. These tools bridge
 | `edit.ts` | String-based find/replace editing with uniqueness validation |
 | `glob.ts` | Pattern-based file discovery using find command |
 | `grep.ts` | Ripgrep-powered content search with context and filtering |
-| `ask-user.ts` | Interactive Q&A with simple and structured question formats |
+| `ask-user.ts` | Deferred structured user Q&A rendered by the client |
 | `enter-plan-mode.ts` | Enter planning mode for explore-then-execute workflows |
 | `exit-plan-mode.ts` | Exit planning mode and submit plan for approval |
 | `skill.ts` | Activate pre-loaded skills from SKILL.md files |
@@ -32,7 +32,7 @@ The tools module implements all 15 AI agent tools in BashKit. These tools bridge
 - `createEditTool(sandbox, config?)` -- String replacement editing
 - `createGlobTool(sandbox, config?)` -- File pattern matching
 - `createGrepTool(sandbox, config?)` -- Content search with ripgrep
-- `createAskUserTool(config?)` -- User interaction tool
+- `createAskUserTool(config?)` -- Deferred user interaction tool
 - `createEnterPlanModeTool(state, onEnter?)` -- Planning mode entry
 - `createExitPlanModeTool(onPlanSubmit?)` -- Planning mode exit
 - `createSkillTool(config)` -- Skill activation
@@ -44,14 +44,14 @@ The tools module implements all 15 AI agent tools in BashKit. These tools bridge
 ### Output Types
 Each tool exports `<Name>Output` for success and `<Name>Error` for errors:
 - Sandbox tools: `BashOutput | BashError`, `ReadOutput | ReadError`, etc.
-- Interactive tools: `AskUserOutput | AskUserError`, etc.
+- Interactive tools: `AskUserOutput`, etc.
 - Workflow tools: `TaskOutput | TaskError`, `TodoWriteOutput | TodoWriteError`
 - Web tools: `WebSearchOutput | WebSearchError`, `WebFetchOutput | WebFetchError`
 
 ### Configuration Types
 - `AgentConfig` -- Top-level config for createAgentTools()
 - `ToolConfig` -- Per-tool config (timeout, allowedPaths, maxFileSize, etc.)
-- `AskUserConfig` -- Ask user handlers
+- `AskUserConfig` -- AskUser AI SDK tool options
 - `SkillConfig` -- Skill metadata and sandbox
 - `TaskToolConfig` -- Sub-agent configuration (includes optional `budget` for auto-wiring cost tracking)
 - `ModelRegistryConfig` -- Model registry config (provider, apiKey) for fetching model info
@@ -66,7 +66,7 @@ Each tool exports `<Name>Output` for success and `<Name>Error` for errors:
 - Bash, Read, Write, Edit, Glob, Grep -- Direct sandbox operations via Sandbox interface
 
 **Interactive Tools** (opt-in via config):
-- AskUser -- User Q&A with simple and structured formats
+- AskUser -- Deferred structured user Q&A rendered by the client
 - EnterPlanMode, ExitPlanMode -- Plan-then-execute workflow
 - Skill -- Load specialized instructions from SKILL.md files
 
@@ -81,7 +81,7 @@ Each tool exports `<Name>Output` for success and `<Name>Error` for errors:
 ### Data Flow
 
 1. **Tool Creation**: `createAgentTools()` → individual `create*Tool()` factories → `tool()` from AI SDK
-2. **Execution**: AI model calls tool → `execute()` function → sandbox operation or external API → return Output or Error
+2. **Execution**: AI model calls tool → `execute()` function or deferred client round-trip → sandbox operation or external API → return Output or Error
 3. **Caching** (optional): `resolveCache()` wraps cacheable tools with `cached()` from cache module
 4. **Model Registry** (optional): `createAgentTools()` fetches model info (pricing + context lengths) from a provider (e.g., OpenRouter). Data is shared with budget tracking and returned as `openRouterModels` in the result.
 5. **Budget** (optional): `createAgentTools()` creates a `BudgetTracker` from config, using pricing derived from model registry or manual overrides. Returns it for wiring into `onStepFinish`/`stopWhen`. Auto-wires into Task tool sub-agents.