goatchain 0.0.32 → 0.0.33

package/README.md

@@ -28,7 +28,6 @@ hooks: {
 ```
 
 If you need both, use:
-
 - `preToolUse` to rewrite tool arguments/tool call
 - `permissionRequest` to allow or block execution
 
@@ -116,7 +115,6 @@ const session = await agent.createSession({
 interface CreateSessionOptions {
   sessionId?: string // Custom session ID
   model?: ModelRef // Optional model override
-  variants?: ModelRef[] // Optional fallback model refs
   maxIterations?: number // Max agent loop iterations (default: 1000)
   cwd?: string // Working directory for file operations
   messageQueueConfig?: {
@@ -126,15 +124,14 @@ interface CreateSessionOptions {
   requestParams?: {
     temperature?: number // Model temperature
     maxTokens?: number // Max output tokens
-    stop?: string[] // Optional stop sequences
-    [key: string]: unknown // Provider-specific request params
+    topP?: number // Nucleus sampling parameter
   }
 }
 ```
 
 ### Working Directory (CWD) Configuration
 
-You can set a working directory for the session, which will be automatically applied to tools that support `setCwd()` (for example `Read`, `Write`, `Edit`, `Glob`, `Grep`, and `Bash`):
+You can set a working directory for the session, which will be automatically applied to all file operation tools (Read, Write, Edit, Glob, Grep, Bash, AstGrepSearch, AstGrepReplace):
 
 ```typescript
 // Set CWD when creating a session
@@ -276,7 +273,7 @@ for await (const event of session.receive()) {
       break
 
     case 'tool_call_start':
-      console.log(`\nCalling tool: ${event.toolName ?? event.callId}`)
+      console.log(`\nCalling tool: ${event.name}`)
       break
 
     case 'tool_result':
@@ -292,28 +289,30 @@ for await (const event of session.receive()) {
       console.log(`\nConversation done: ${event.stopReason}`)
       console.log(`Total tokens: ${event.usage?.totalTokens}`)
       break
+
+    case 'error':
+      console.error(`Error: ${event.error}`)
+      break
   }
 }
 ```
 
 ### Session Event Types
 
-| Event Type                                              | Description                                      | Key Fields                                         |
-| ------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
-| `session_created`                                       | New session stream starts                        | `sessionId`                                        |
-| `text_start` / `text_delta` / `text_end`                | Assistant text stream                            | `delta`, `content`                                 |
-| `thinking_start` / `thinking_delta` / `thinking_end`    | Model reasoning stream                           | `delta`, `content`                                 |
-| `tool_call_start` / `tool_call_delta` / `tool_call_end` | Tool call lifecycle                              | `callId`, `toolName`, `toolCall`                   |
-| `tool_output_start` / `tool_output_delta`               | Live tool stdout/stderr stream                   | `tool_call_id`, `delta`, `isStderr`                |
-| `tool_result`                                           | Tool execution result                            | `tool_call_id`, `result`, `isError`                |
-| `tool_approval_requested`                               | High-risk tool needs approval                    | `tool_call_id`, `toolName`, `riskLevel`, `args`    |
-| `requires_action`                                       | Execution paused for approval or AskUser answers | `kind`, `checkpoint`, `checkpointRef`, `questions` |
-| `tool_skipped`                                          | Tool execution skipped                           | `tool_call_id`, `toolName`, `reason`               |
-| `iteration_start` / `iteration_end`                     | Agent loop iteration lifecycle                   | `iteration`, `usage`                               |
-| `subagent_event`                                        | Forwarded subagent status                        | `subagentId`, `subagentType`, `phase`              |
-| `compression_start` / `compression_end`                 | Context compression lifecycle                    | `tokensBefore`, `tokensAfter`, `strategy`          |
-| `hook_evaluation`                                       | Prompt-hook evaluation lifecycle                 | `hookName`, `phase`, `status`                      |
-| `done`                                                  | Stream finished                                  | `stopReason`, `modelStopReason`, `error`, `usage`  |
+| Event Type        | Description                 | Key Fields            |
+| ----------------- | --------------------------- | --------------------- |
+| `iteration_start` | Agent loop iteration begins | `iteration`           |
+| `text_delta`      | Partial text response       | `delta`               |
+| `thinking_start`  | Reasoning phase begins      | -                     |
+| `thinking_delta`  | Reasoning content           | `delta`               |
+| `thinking_end`    | Reasoning phase ends        | -                     |
+| `tool_call_start` | Tool invocation begins      | `name`, `id`          |
+| `tool_call_delta` | Tool arguments stream       | `delta`               |
+| `tool_call_end`   | Tool call complete          | `name`, `args`        |
+| `tool_result`     | Tool execution result       | `result`, `error`     |
+| `iteration_end`   | Iteration complete          | `usage`, `iteration`  |
+| `done`            | Stream finished             | `stopReason`, `usage` |
+| `error`           | Error occurred              | `error`               |
 
 ### Session State Management
 
@@ -322,7 +321,7 @@ for await (const event of session.receive()) {
 console.log(session.messages) // Message[]
 
 // Check session status
-console.log(session.status) // 'active' | 'paused' | 'completed' | 'error' | 'archived'
+console.log(session.status) // 'idle' | 'running' | 'completed' | 'error'
 
 // Get token usage
 console.log(session.usage)
@@ -382,8 +381,8 @@ for await (const event of session.receive()) {
   }
 }
 
-// Session now contains the full conversation history plus the system prompt
-console.log(session.messages.length) // 5 (system + 2 user + 2 assistant)
+// Session now contains full conversation history
+console.log(session.messages.length) // 4 (2 user, 2 assistant)
 ```
 
 ### Resuming Sessions
@@ -420,7 +419,7 @@ for await (const event of resumed.receive()) {
 }
 ```
 
-### Session Utilities
+### Session Lifecycle Hooks
 
 ```typescript
 // Add message manually
@@ -432,9 +431,8 @@ session.addMessage({
 // Save session state manually
 await session.save()
 
-// Advanced: direct message mutation is allowed, but prefer snapshots/checkpoints
-// when you need reproducible restore flows.
-session.messages.push({ role: 'assistant', content: 'Synthetic entry' })
+// Clear session history
+session.messages = []
 ```
 
 ## 🤖 Agent Configuration
@@ -479,9 +477,7 @@ interface AgentOptions {
 agent.setModel({ provider: 'openai', modelId: 'gpt-4o-mini' })
 
 // Switch to another concrete model client instance
-const otherModelClient = createModel({
-  adapter: createOpenAIAdapter({ defaultModelId: 'gpt-4o' }),
-})
+const otherModelClient = createModel({ adapter: createOpenAIAdapter({ defaultModelId: 'gpt-4o' }) })
 agent.setModel(otherModelClient)
 ```
 
@@ -508,22 +504,21 @@ await sessionManager.destroy('session-id')
 
 GoatChain SDK exports the following built-in tools:
 
-| Tool Class          | Runtime Name      | Category    | Purpose                                                                   |
-| ------------------- | ----------------- | ----------- | ------------------------------------------------------------------------- |
-| `ReadTool`          | `Read`            | File        | Read file content (text, binary metadata, and selected converted formats) |
-| `WriteTool`         | `Write`           | File        | Create or overwrite files                                                 |
-| `EditTool`          | `Edit`            | File        | In-place text replacement edits                                           |
-| `GlobTool`          | `Glob`            | File/Search | Find files by glob pattern                                                |
-| `GrepTool`          | `Grep`            | File/Search | Search file contents by pattern                                           |
-| `BashTool`          | `Bash`            | Command     | Execute shell commands                                                    |
-| `WebSearchTool`     | `WebSearch`       | Web         | Search the web (e.g. via Serper API)                                      |
-| `WebFetchTool`      | `WebFetch`        | Web         | Fetch and extract content from a specific URL                             |
-| `TaskTool`          | `Task`            | Subagent    | Run a registered subagent task (for example Explore)                      |
-| `TodoWriteTool`     | `TodoWrite`       | Planning    | Manage structured todo lists                                              |
-| `TodoPlanTool`      | `TodoPlan`        | Planning    | Create/update planning todos for plan flows                               |
-| `AskUserTool`       | `AskUserQuestion` | Interaction | Ask the user structured follow-up questions                               |
-| `EnterPlanModeTool` | `EnterPlanMode`   | Mode        | Enter plan mode                                                           |
-| `ExitPlanModeTool`  | `ExitPlanMode`    | Mode        | Exit plan mode                                                            |
+| Tool Class | Runtime Name | Category | Purpose |
+| --- | --- | --- | --- |
+| `ReadTool` | `Read` | File | Read file content (text, binary metadata, and selected converted formats) |
+| `WriteTool` | `Write` | File | Create or overwrite files |
+| `EditTool` | `Edit` | File | In-place text replacement edits |
+| `GlobTool` | `Glob` | File/Search | Find files by glob pattern |
+| `GrepTool` | `Grep` | File/Search | Search file contents by pattern |
+| `BashTool` | `Bash` | Command | Execute shell commands |
+| `WebSearchTool` | `WebSearch` | Web | Search the web (e.g. via Serper API) |
+| `WebFetchTool` | `WebFetch` | Web | Fetch and extract content from a specific URL |
+| `TodoWriteTool` | `TodoWrite` | Planning | Manage structured todo lists |
+| `TodoPlanTool` | `TodoPlan` | Planning | Create/update planning todos for plan flows |
+| `AskUserTool` | `AskUserQuestion` | Interaction | Ask the user structured follow-up questions |
+| `EnterPlanModeTool` | `EnterPlanMode` | Mode | Enter plan mode |
+| `ExitPlanModeTool` | `ExitPlanMode` | Mode | Exit plan mode |
 
 ```typescript
 import {
@@ -626,14 +621,14 @@ tools.register(
 
 **How each file tool uses `cwd`:**
 
-| Tool        | What it does                                      | How `cwd` is applied                     | Per-call override                      | Extra sandbox options                                   |
-| ----------- | ------------------------------------------------- | ---------------------------------------- | -------------------------------------- | ------------------------------------------------------- |
-| `ReadTool`  | Reads files (and some converted formats)          | Relative `file_path` resolves from `cwd` | `file_path` can be absolute            | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
-| `WriteTool` | Writes/overwrites files                           | Relative `file_path` resolves from `cwd` | `file_path` can be absolute            | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
-| `EditTool`  | Replaces `old_string` with `new_string` in a file | Relative `file_path` resolves from `cwd` | `file_path` can be absolute            | `fileBlacklist`, `disableBlacklist`                     |
-| `GlobTool`  | Finds files by pattern                            | Search root defaults to `cwd`            | `path` argument can change search root | `fileBlacklist`, `disableBlacklist`                     |
-| `GrepTool`  | Searches text content in files                    | Search runs under `cwd`                  | `path` argument narrows search scope   | `fileBlacklist`, `disableBlacklist`                     |
-| `BashTool`  | Runs shell commands                               | Commands execute in `cwd`                | `workdir` argument overrides per call  | None                                                    |
+| Tool | What it does | How `cwd` is applied | Per-call override | Extra sandbox options |
+| --- | --- | --- | --- | --- |
+| `ReadTool` | Reads files (and some converted formats) | Relative `file_path` resolves from `cwd` | `file_path` can be absolute | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
+| `WriteTool` | Writes/overwrites files | Relative `file_path` resolves from `cwd` | `file_path` can be absolute | `allowedDirectory`, `fileBlacklist`, `disableBlacklist` |
+| `EditTool` | Replaces `old_string` with `new_string` in a file | Relative `file_path` resolves from `cwd` | `file_path` can be absolute | `fileBlacklist`, `disableBlacklist` |
+| `GlobTool` | Finds files by pattern | Search root defaults to `cwd` | `path` argument can change search root | `fileBlacklist`, `disableBlacklist` |
+| `GrepTool` | Searches text content in files | Search runs under `cwd` | `path` argument narrows search scope | `fileBlacklist`, `disableBlacklist` |
+| `BashTool` | Runs shell commands | Commands execute in `cwd` | `workdir` argument overrides per call | None |
 
 **Directory & Protection Options:**
 
@@ -746,41 +741,26 @@ interface AgentHooks {
   userPromptSubmit?:
     | ((ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>)
     | PromptHookEntry
-    | Array<
-        | ((ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>)
-        | PromptHookEntry
-      >
+    | Array<((ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>) | PromptHookEntry>
 
   // Tool lifecycle
   // - Can modify tool call with modifiedToolCall
   preToolUse?:
     | ((ctx: ToolHookContext) => Promise<PreToolUseResult | void>)
     | PromptHookEntry
-    | Array<
-        | ((ctx: ToolHookContext) => Promise<PreToolUseResult | void>)
-        | PromptHookEntry
-      >
+    | Array<((ctx: ToolHookContext) => Promise<PreToolUseResult | void>) | PromptHookEntry>
   permissionRequest?:
     | ((ctx: ToolHookContext) => Promise<PermissionRequestResult>)
     | PromptHookEntry
-    | Array<
-        | ((ctx: ToolHookContext) => Promise<PermissionRequestResult>)
-        | PromptHookEntry
-      >
+    | Array<((ctx: ToolHookContext) => Promise<PermissionRequestResult>) | PromptHookEntry>
   postToolUse?:
     | ((ctx: ToolHookContext, result: unknown) => Promise<void>)
     | PromptHookEntry
-    | Array<
-        | ((ctx: ToolHookContext, result: unknown) => Promise<void>)
-        | PromptHookEntry
-      >
+    | Array<((ctx: ToolHookContext, result: unknown) => Promise<void>) | PromptHookEntry>
   postToolUseFailure?:
     | ((ctx: ToolHookContext, error: Error) => Promise<void>)
     | PromptHookEntry
-    | Array<
-        | ((ctx: ToolHookContext, error: Error) => Promise<void>)
-        | PromptHookEntry
-      >
+    | Array<((ctx: ToolHookContext, error: Error) => Promise<void>) | PromptHookEntry>
 
   // Subagent lifecycle (used by parallel task/subagent middleware)
   subagentStart?: (ctx: SubagentStartContext) => Promise<void>
@@ -1017,12 +997,7 @@ const agent = new Agent({
   name: 'MyAgent',
   systemPrompt: 'You are helpful.',
   model,
-  tools: (() => {
-    const tools = new ToolRegistry()
-    tools.register(new ReadTool())
-    tools.register(new WriteTool())
-    return tools
-  })(),
+  tools: new ToolRegistry().register(new ReadTool()).register(new WriteTool()),
 })
 
 // Create session with hooks
@@ -1257,7 +1232,7 @@ const session = await agent.createSession({
 
 ### Tool Context
 
-The `toolContext` parameter in `send()` and `receive()` is used for approval state and AskUser resume data:
+The `toolContext` parameter in `send()` and `receive()` allows passing additional context:
 
 ```typescript
 session.send('Do something risky', {
@@ -1270,14 +1245,8 @@ session.send('Do something risky', {
         tool_call_id_456: { approved: false, reason: 'Too dangerous' },
       },
     },
-    askUser: {
-      answers: {
-        tool_call_id_789: {
-          framework: 'React',
-          styling: 'Tailwind CSS',
-        },
-      },
-    },
+    // Your custom context
+    custom: { userId: '123', environment: 'production' },
   },
 })
 ```
@@ -1294,7 +1263,7 @@ outer:before → inner:before → exec (model.stream) → inner:after → outer:
 
 ```typescript
 // Add named middleware (recommended)
-await agent.use(async (state, next) => {
+agent.use(async (state, next) => {
   const start = Date.now()
   console.log(`[${state.iteration}] Before model call`)
 
@@ -1311,7 +1280,7 @@ agent.removeMiddleware('logging')
 console.log(agent.middlewareNames) // ['logging', 'compression', ...]
 
 // Use unsubscribe function
-const unsubscribe = await agent.use(middleware, 'temp')
+const unsubscribe = agent.use(middleware, 'temp')
 unsubscribe() // Remove middleware
 ```
 
@@ -1325,10 +1294,10 @@ Adds planning phase before execution:
 import { createPlanModeMiddleware } from 'goatchain'
 
 // Automatically named 'plan_mode'
-await agent.use(createPlanModeMiddleware())
+agent.use(createPlanModeMiddleware())
 
 // With custom configuration
-await agent.use(
+agent.use(
   createPlanModeMiddleware({
     name: 'my-plan', // Custom name
     planPrompt: 'Create a detailed plan...', // Custom prompt
@@ -1338,36 +1307,35 @@ await agent.use(
 
 #### Context Compression Middleware
 
-Automatically compresses context from the full raw transcript when the prompt approaches the model context window. The middleware now:
-
-- reuses any persisted rolling summary first
-- removes old `tool` messages before touching the current round
-- preserves the last user round
-- performs at most one AI summary pass per overflow event
-- guarantees the final prompt stays within `contextLength` or fails locally before the model call
-- can emit per-stage snapshots in the large E2E example for inspection
+Automatically compresses context when token limit is reached using a two-stage strategy:
 
 ```typescript
 import { createContextCompressionMiddleware } from 'goatchain'
 
 // Automatically named 'context_compression'
-await agent.use(
+agent.use(
   createContextCompressionMiddleware({
-    contextLength: 128000,
+    maxTokens: 128000,
+    protectedTurns: 2, // Keep last 2 conversation turns
+    model: model,
+    stateStore: agent.stateStore,
+    toolCompressionTarget: 0.45, // Compress to 45% of maxTokens
+    minKeepToolResults: 5, // Keep last 5 tool results
+    // Optional: Enable detailed logging
+    enableLogging: true,
+    logFilePath: 'compression-logs.jsonl',
   }),
 )
 ```
 
-The large E2E example writes `round-N/stage1.json` through `stage4.json` under `examples/output/context-compression-large-e2e/` by default, so you can inspect each compression step directly.
-
-See [`src/spec/middleware.md`](./src/spec/middleware.md) for the full middleware and compression spec.
+See [Context Compression Logging Guide](./docs/context-compression-logging.md) for details on monitoring compression behavior.
 
 ### Custom Middleware Examples
 
 #### Logging Middleware
 
 ```typescript
-await agent.use(async (state, next) => {
+agent.use(async (state, next) => {
   console.log(`Iteration ${state.iteration}:`, {
     messages: state.messages.length,
     pendingTools: state.pendingToolCalls.length,
@@ -1387,7 +1355,7 @@ await agent.use(async (state, next) => {
 #### Error Handling Middleware
 
 ```typescript
-await agent.use(async (state, next) => {
+agent.use(async (state, next) => {
   try {
     return await next(state)
   } catch (error) {
@@ -1407,7 +1375,7 @@ import { RateLimiter } from 'some-rate-limiter'
 
 const limiter = new RateLimiter({ requestsPerMinute: 60 })
 
-await agent.use(async (state, next) => {
+agent.use(async (state, next) => {
   await limiter.acquire()
   return next(state)
 }, 'rate-limiter')
@@ -1416,7 +1384,7 @@ await agent.use(async (state, next) => {
 #### Custom Retry Middleware
 
 ```typescript
-await agent.use(async (state, next) => {
+agent.use(async (state, next) => {
   let retries = 3
 
   while (retries > 0) {
@@ -1446,12 +1414,10 @@ interface AgentLoopState {
   iteration: number // Current iteration number
   pendingToolCalls: ToolCallWithResult[] // Pending tool executions
   currentResponse: string // Current LLM response
-  currentThinking?: string // Current reasoning content, if the model emits it
   shouldContinue: boolean // Whether to continue loop
   stopReason?: string // Reason for stopping
-  usage: Usage // Cumulative token usage
+  usage?: Usage // Token usage
   error?: Error // Error if any
-  metadata: Record<string, unknown> // Middleware/hook shared runtime data
 }
 ```
 
@@ -1574,15 +1540,8 @@ Implement custom state stores:
 interface StateStore {
   deleteOnComplete: boolean
 
-  save<T>(sessionId: string, key: string, data: T): Promise<void>
-  load<T>(sessionId: string, key: string): Promise<T | undefined>
-  delete(sessionId: string, key: string): Promise<void>
-  listKeys(sessionId: string): Promise<string[]>
-  listSessions(): Promise<string[]>
-
-  // Checkpoint helpers
   saveCheckpoint(checkpoint: AgentLoopCheckpoint): Promise<void>
-  loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | undefined>
+  loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | null>
   deleteCheckpoint(sessionId: string): Promise<void>
   listCheckpoints(): Promise<AgentLoopCheckpoint[]>
 }
@@ -1600,8 +1559,17 @@ interface AgentLoopCheckpoint {
 ### Manual Checkpoint Management
 
 ```typescript
-// Prefer SDK-managed checkpoints during session.receive().
-// You can still inspect or clean them up manually:
+// Save checkpoint manually
+await stateStore.saveCheckpoint({
+  sessionId: session.id,
+  messages: session.messages,
+  iteration: 3,
+  usage: session.usage,
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+})
+
+// Load checkpoint
 const checkpoint = await stateStore.loadCheckpoint('session-id')
 
 // List all checkpoints
@@ -1681,7 +1649,7 @@ for await (const event of session.receive()) {
   if (event.type === 'text_delta') {
     process.stdout.write(event.delta)
   } else if (event.type === 'tool_call_start') {
-    console.log(`\nCalling: ${event.toolName}`)
+    console.log(`\nCalling: ${event.name}`)
   } else if (event.type === 'tool_result') {
     console.log(`Result: ${JSON.stringify(event.result).slice(0, 100)}...`)
   }
@@ -1762,7 +1730,7 @@ const agent = new Agent({
 })
 
 // Add logging middleware
-await agent.use(async (state, next) => {
+agent.use(async (state, next) => {
   console.log(`\n=== Iteration ${state.iteration} ===`)
   const result = await next(state)
   console.log(`Tokens used: ${result.usage?.totalTokens || 0}`)
@@ -1770,7 +1738,7 @@ await agent.use(async (state, next) => {
 }, 'logger')
 
 // Add plan mode
-await agent.use(createPlanModeMiddleware())
+agent.use(createPlanModeMiddleware())
 
 const session = await agent.createSession()
 session.send('Create a todo list app with React and TypeScript')
@@ -1836,12 +1804,7 @@ import {
   Agent,
   createModel,
   createOpenAIAdapter,
-  ToolRegistry,
-  ReadTool,
-  WriteTool,
-  EditTool,
-  GlobTool,
-  GrepTool,
+  createBuiltinTools,
 } from 'goatchain'
 
 const model = createModel({
@@ -1851,18 +1814,11 @@ const model = createModel({
   }),
 })
 
-const tools = new ToolRegistry()
-tools.register(new ReadTool())
-tools.register(new WriteTool())
-tools.register(new EditTool())
-tools.register(new GlobTool())
-tools.register(new GrepTool())
-
 const agent = new Agent({
   name: 'File Agent',
   systemPrompt: 'You are a file management assistant.',
   model,
-  tools,
+  tools: createBuiltinTools(), // All file tools included
 })
 
 // Set working directory at session creation
@@ -1969,7 +1925,7 @@ for await (const event of session.receive()) {
   if (event.type === 'text_delta') {
     process.stdout.write(event.delta)
   } else if (event.type === 'tool_call_start') {
-    console.log(`\n[Tool] ${event.toolName}`)
+    console.log(`\n[Tool] ${event.name}`)
   }
 }
 ```
@@ -2158,7 +2114,7 @@ session.setCwd('/path/to/project')
 #### Properties
 
 - `id: string` - Session ID
-- `status: SessionStatus` - Session status (`'active' | 'paused' | 'completed' | 'error' | 'archived'`)
+- `status: SessionStatus` - Session status ('idle' | 'running' | 'completed' | 'error')
 - `messages: Message[]` - Message history
 - `usage: Usage` - Token usage statistics
 - `createdAt: number` - Creation timestamp
@@ -2169,12 +2125,9 @@ session.setCwd('/path/to/project')
 ```typescript
 interface Message {
   role: 'system' | 'user' | 'assistant' | 'tool'
-  content: MessageContent
-  reasoning_content?: string // Assistant messages
-  tool_calls?: ToolCall[] // Assistant messages
-  tool_call_id?: string // Tool messages
-  name?: string
-  isError?: boolean // Tool messages
+  content: string | ToolCall[] | ToolResult[]
+  name?: string // For tool messages
+  toolCallId?: string // For tool messages
 }
 ```
 
@@ -2192,17 +2145,10 @@ interface Usage {
 
 ```typescript
 type AgentEvent =
-  | TextStartEvent
   | TextDeltaEvent
-  | TextEndEvent
   | ToolCallStartEvent
   | ToolCallDeltaEvent
   | ToolCallEndEvent
-  | ToolOutputStartEvent
-  | ToolOutputDeltaEvent
-  | ToolApprovalRequestedEvent
-  | RequiresActionEvent
-  | ToolSkippedEvent
   | ToolResultEvent
   | ThinkingStartEvent
   | ThinkingDeltaEvent
@@ -2210,6 +2156,7 @@ type AgentEvent =
   | IterationStartEvent
   | IterationEndEvent
   | DoneEvent
+  | ErrorEvent
 
 interface TextDeltaEvent {
   type: 'text_delta'
@@ -2218,15 +2165,8 @@ interface TextDeltaEvent {
 
 interface ToolCallStartEvent {
   type: 'tool_call_start'
-  callId: string
-  toolName?: string
-}
-
-interface RequiresActionEvent {
-  type: 'requires_action'
-  kind: 'tool_approval' | 'ask_user'
-  checkpoint?: AgentLoopCheckpoint
-  checkpointRef?: { sessionId: string }
+  id: string
+  name: string
 }
 
 interface ToolResultEvent {
@@ -2238,7 +2178,6 @@ interface ToolResultEvent {
 
 interface DoneEvent {
   type: 'done'
-  finalResponse?: string
   stopReason:
     | 'max_iterations'
     | 'final_response'
@@ -2246,13 +2185,6 @@ interface DoneEvent {
     | 'cancelled'
     | 'approval_required'
     | 'max_follow_ups'
-  modelStopReason?: 'tool_call' | 'final' | 'length' | 'error' | 'cancelled'
-  error?: {
-    code?: string
-    message: string
-    status?: number
-    retryable?: boolean
-  }
   usage?: Usage
 }
 ```

package/dist/index.d.ts

@@ -37,4 +37,4 @@ export { AskUserTool, BashTool, EditTool, GlobTool, GrepTool, ReadTool, softWrap
 export type { BashArgs, BashResult, RiskLevel, ToolApprovalResult, ToolApprovalSettings, ToolApprovalStrategy, ToolExecutionContext, ToolExecutionContextInput, ToolRunUsage, } from './tool';
 export type { AskUserArgs, AskUserResult, DeliveryMode, EditArgs, EditResult, FetchFormat, GlobArgs, GlobResult, GrepArgs, GrepOutputMode, GrepResult, Question, QuestionOption, ReadArgs, ReadResult, TodoItem, TodoPlanArgs, TodoPlanResult, TodoStatus, TodoWriteArgs, TodoWriteResult, WebFetchArgs, WebFetchResult, WebSearchArgs, WebSearchResult, WriteArgs, WriteResult, } from './tool';
 export * from './tool/converters';
-export type { AgentEvent, AgentEventType, AgentLoopCheckpoint, AssistantMessage, BaseEvent, CallModelOnceOptions, CallModelOnceResult, CallToolResult, CompletionAssessedEvent, CompressionEndEvent, CompressionStartEvent, ContentBlock, DoneEvent, HookEvaluationEvent, ImageContent, IterationEndEvent, IterationStartEvent, JSONSchemaProperty, Message, MessageContent, MessageRole, SessionSnapshot, SystemMessage, TextContent, TextDeltaEvent, TextEndEvent, TextStartEvent, ThinkingDeltaEvent, Tool, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolMessage, ToolResultEvent, Usage, UserMessage, } from './types';
+export type { AgentEvent, AgentEventType, AgentLoopCheckpoint, AssistantMessage, BaseEvent, CallModelOnceOptions, CallModelOnceResult, CallToolResult, CompletionAssessedEvent, CompressionEndEvent, CompressionStartEvent, ContentBlock, DoneEvent, HookEvaluationEvent, ImageContent, IterationEndEvent, IterationStartEvent, JSONSchemaProperty, Message, MessageContent, MessageRole, SystemMessage, TextContent, TextDeltaEvent, TextEndEvent, TextStartEvent, ThinkingDeltaEvent, Tool, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolMessage, ToolResultEvent, Usage, UserMessage, } from './types';