goatchain 0.0.30 → 0.0.32

package/README.md

@@ -28,6 +28,7 @@ hooks: {
 ```
 
 If you need both, use:
+
 - `preToolUse` to rewrite tool arguments/tool call
 - `permissionRequest` to allow or block execution
 
@@ -115,6 +116,7 @@ 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?: {
@@ -124,14 +126,15 @@ interface CreateSessionOptions {
   requestParams?: {
     temperature?: number // Model temperature
     maxTokens?: number // Max output tokens
-    topP?: number // Nucleus sampling parameter
+    stop?: string[] // Optional stop sequences
+    [key: string]: unknown // Provider-specific request params
   }
 }
 ```
 
 ### Working Directory (CWD) Configuration
 
-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):
+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`):
 
 ```typescript
 // Set CWD when creating a session
@@ -273,7 +276,7 @@ for await (const event of session.receive()) {
       break
 
     case 'tool_call_start':
-      console.log(`\nCalling tool: ${event.name}`)
+      console.log(`\nCalling tool: ${event.toolName ?? event.callId}`)
       break
 
     case 'tool_result':
@@ -289,30 +292,28 @@ 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            |
-| ----------------- | --------------------------- | --------------------- |
-| `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`               |
+| 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`  |
 
 ### Session State Management
 
@@ -321,7 +322,7 @@ for await (const event of session.receive()) {
 console.log(session.messages) // Message[]
 
 // Check session status
-console.log(session.status) // 'idle' | 'running' | 'completed' | 'error'
+console.log(session.status) // 'active' | 'paused' | 'completed' | 'error' | 'archived'
 
 // Get token usage
 console.log(session.usage)
@@ -381,8 +382,8 @@ for await (const event of session.receive()) {
   }
 }
 
-// Session now contains full conversation history
-console.log(session.messages.length) // 4 (2 user, 2 assistant)
+// Session now contains the full conversation history plus the system prompt
+console.log(session.messages.length) // 5 (system + 2 user + 2 assistant)
 ```
 
 ### Resuming Sessions
@@ -419,7 +420,7 @@ for await (const event of resumed.receive()) {
 }
 ```
 
-### Session Lifecycle Hooks
+### Session Utilities
 
 ```typescript
 // Add message manually
@@ -431,8 +432,9 @@ session.addMessage({
 // Save session state manually
 await session.save()
 
-// Clear session history
-session.messages = []
+// Advanced: direct message mutation is allowed, but prefer snapshots/checkpoints
+// when you need reproducible restore flows.
+session.messages.push({ role: 'assistant', content: 'Synthetic entry' })
 ```
 
 ## 🤖 Agent Configuration
@@ -477,7 +479,9 @@ 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)
 ```
 
@@ -504,21 +508,22 @@ 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 |
-| `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                             |
+| `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                                                            |
 
 ```typescript
 import {
@@ -621,14 +626,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:**
 
@@ -741,26 +746,41 @@ 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>
@@ -997,7 +1017,12 @@ const agent = new Agent({
   name: 'MyAgent',
   systemPrompt: 'You are helpful.',
   model,
-  tools: new ToolRegistry().register(new ReadTool()).register(new WriteTool()),
+  tools: (() => {
+    const tools = new ToolRegistry()
+    tools.register(new ReadTool())
+    tools.register(new WriteTool())
+    return tools
+  })(),
 })
 
 // Create session with hooks
@@ -1232,7 +1257,7 @@ const session = await agent.createSession({
 
 ### Tool Context
 
-The `toolContext` parameter in `send()` and `receive()` allows passing additional context:
+The `toolContext` parameter in `send()` and `receive()` is used for approval state and AskUser resume data:
 
 ```typescript
 session.send('Do something risky', {
@@ -1245,8 +1270,14 @@ session.send('Do something risky', {
         tool_call_id_456: { approved: false, reason: 'Too dangerous' },
       },
     },
-    // Your custom context
-    custom: { userId: '123', environment: 'production' },
+    askUser: {
+      answers: {
+        tool_call_id_789: {
+          framework: 'React',
+          styling: 'Tailwind CSS',
+        },
+      },
+    },
   },
 })
 ```
@@ -1263,7 +1294,7 @@ outer:before → inner:before → exec (model.stream) → inner:after → outer:
 
 ```typescript
 // Add named middleware (recommended)
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   const start = Date.now()
   console.log(`[${state.iteration}] Before model call`)
 
@@ -1280,7 +1311,7 @@ agent.removeMiddleware('logging')
 console.log(agent.middlewareNames) // ['logging', 'compression', ...]
 
 // Use unsubscribe function
-const unsubscribe = agent.use(middleware, 'temp')
+const unsubscribe = await agent.use(middleware, 'temp')
 unsubscribe() // Remove middleware
 ```
 
@@ -1294,10 +1325,10 @@ Adds planning phase before execution:
 import { createPlanModeMiddleware } from 'goatchain'
 
 // Automatically named 'plan_mode'
-agent.use(createPlanModeMiddleware())
+await agent.use(createPlanModeMiddleware())
 
 // With custom configuration
-agent.use(
+await agent.use(
   createPlanModeMiddleware({
     name: 'my-plan', // Custom name
     planPrompt: 'Create a detailed plan...', // Custom prompt
@@ -1307,35 +1338,36 @@ agent.use(
 
 #### Context Compression Middleware
 
-Automatically compresses context when token limit is reached using a two-stage strategy:
+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
 
 ```typescript
 import { createContextCompressionMiddleware } from 'goatchain'
 
 // Automatically named 'context_compression'
-agent.use(
+await agent.use(
   createContextCompressionMiddleware({
-    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',
+    contextLength: 128000,
   }),
 )
 ```
 
-See [Context Compression Logging Guide](./docs/context-compression-logging.md) for details on monitoring compression behavior.
+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.
 
 ### Custom Middleware Examples
 
 #### Logging Middleware
 
 ```typescript
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   console.log(`Iteration ${state.iteration}:`, {
     messages: state.messages.length,
     pendingTools: state.pendingToolCalls.length,
@@ -1355,7 +1387,7 @@ agent.use(async (state, next) => {
 #### Error Handling Middleware
 
 ```typescript
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   try {
     return await next(state)
   } catch (error) {
@@ -1375,7 +1407,7 @@ import { RateLimiter } from 'some-rate-limiter'
 
 const limiter = new RateLimiter({ requestsPerMinute: 60 })
 
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   await limiter.acquire()
   return next(state)
 }, 'rate-limiter')
@@ -1384,7 +1416,7 @@ agent.use(async (state, next) => {
 #### Custom Retry Middleware
 
 ```typescript
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   let retries = 3
 
   while (retries > 0) {
@@ -1414,10 +1446,12 @@ 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 // Token usage
+  usage: Usage // Cumulative token usage
   error?: Error // Error if any
+  metadata: Record<string, unknown> // Middleware/hook shared runtime data
 }
 ```
 
@@ -1540,8 +1574,15 @@ 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 | null>
+  loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | undefined>
   deleteCheckpoint(sessionId: string): Promise<void>
   listCheckpoints(): Promise<AgentLoopCheckpoint[]>
 }
@@ -1559,17 +1600,8 @@ interface AgentLoopCheckpoint {
 ### Manual Checkpoint Management
 
 ```typescript
-// 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
+// Prefer SDK-managed checkpoints during session.receive().
+// You can still inspect or clean them up manually:
 const checkpoint = await stateStore.loadCheckpoint('session-id')
 
 // List all checkpoints
@@ -1649,7 +1681,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.name}`)
+    console.log(`\nCalling: ${event.toolName}`)
   } else if (event.type === 'tool_result') {
     console.log(`Result: ${JSON.stringify(event.result).slice(0, 100)}...`)
   }
@@ -1730,7 +1762,7 @@ const agent = new Agent({
 })
 
 // Add logging middleware
-agent.use(async (state, next) => {
+await agent.use(async (state, next) => {
   console.log(`\n=== Iteration ${state.iteration} ===`)
   const result = await next(state)
   console.log(`Tokens used: ${result.usage?.totalTokens || 0}`)
@@ -1738,7 +1770,7 @@ agent.use(async (state, next) => {
 }, 'logger')
 
 // Add plan mode
-agent.use(createPlanModeMiddleware())
+await agent.use(createPlanModeMiddleware())
 
 const session = await agent.createSession()
 session.send('Create a todo list app with React and TypeScript')
@@ -1804,7 +1836,12 @@ import {
   Agent,
   createModel,
   createOpenAIAdapter,
-  createBuiltinTools,
+  ToolRegistry,
+  ReadTool,
+  WriteTool,
+  EditTool,
+  GlobTool,
+  GrepTool,
 } from 'goatchain'
 
 const model = createModel({
@@ -1814,11 +1851,18 @@ 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: createBuiltinTools(), // All file tools included
+  tools,
 })
 
 // Set working directory at session creation
@@ -1925,7 +1969,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.name}`)
+    console.log(`\n[Tool] ${event.toolName}`)
   }
 }
 ```
@@ -2114,7 +2158,7 @@ session.setCwd('/path/to/project')
 #### Properties
 
 - `id: string` - Session ID
-- `status: SessionStatus` - Session status ('idle' | 'running' | 'completed' | 'error')
+- `status: SessionStatus` - Session status (`'active' | 'paused' | 'completed' | 'error' | 'archived'`)
 - `messages: Message[]` - Message history
 - `usage: Usage` - Token usage statistics
 - `createdAt: number` - Creation timestamp
@@ -2125,9 +2169,12 @@ session.setCwd('/path/to/project')
 ```typescript
 interface Message {
   role: 'system' | 'user' | 'assistant' | 'tool'
-  content: string | ToolCall[] | ToolResult[]
-  name?: string // For tool messages
-  toolCallId?: string // For tool messages
+  content: MessageContent
+  reasoning_content?: string // Assistant messages
+  tool_calls?: ToolCall[] // Assistant messages
+  tool_call_id?: string // Tool messages
+  name?: string
+  isError?: boolean // Tool messages
 }
 ```
 
@@ -2145,10 +2192,17 @@ interface Usage {
 
 ```typescript
 type AgentEvent =
+  | TextStartEvent
   | TextDeltaEvent
+  | TextEndEvent
   | ToolCallStartEvent
   | ToolCallDeltaEvent
   | ToolCallEndEvent
+  | ToolOutputStartEvent
+  | ToolOutputDeltaEvent
+  | ToolApprovalRequestedEvent
+  | RequiresActionEvent
+  | ToolSkippedEvent
   | ToolResultEvent
   | ThinkingStartEvent
   | ThinkingDeltaEvent
@@ -2156,7 +2210,6 @@ type AgentEvent =
   | IterationStartEvent
   | IterationEndEvent
   | DoneEvent
-  | ErrorEvent
 
 interface TextDeltaEvent {
   type: 'text_delta'
@@ -2165,8 +2218,15 @@ interface TextDeltaEvent {
 
 interface ToolCallStartEvent {
   type: 'tool_call_start'
-  id: string
-  name: string
+  callId: string
+  toolName?: string
+}
+
+interface RequiresActionEvent {
+  type: 'requires_action'
+  kind: 'tool_approval' | 'ask_user'
+  checkpoint?: AgentLoopCheckpoint
+  checkpointRef?: { sessionId: string }
 }
 
 interface ToolResultEvent {
@@ -2178,6 +2238,7 @@ interface ToolResultEvent {
 
 interface DoneEvent {
   type: 'done'
+  finalResponse?: string
   stopReason:
     | 'max_iterations'
     | 'final_response'
@@ -2185,6 +2246,13 @@ 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, 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, SessionSnapshot, SystemMessage, TextContent, TextDeltaEvent, TextEndEvent, TextStartEvent, ThinkingDeltaEvent, Tool, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolMessage, ToolResultEvent, Usage, UserMessage, } from './types';