goatchain 0.0.23 → 0.0.25

package/README.md

@@ -4,6 +4,33 @@
 
 [![npm version](https://badge.fury.io/js/goatchain.svg)](https://badge.fury.io/js/goatchain)
 
+## ⚠️ Breaking Change: `preToolUse` vs `permissionRequest`
+
+`preToolUse` is now only for mutating tool calls (`modifiedToolCall`).
+Permission decisions (`allow` / `deny`) must be handled in `permissionRequest`.
+
+### Migration
+
+Before (old pattern):
+
+```typescript
+hooks: {
+  preToolUse: async () => ({ allow: true }),
+}
+```
+
+After (current pattern):
+
+```typescript
+hooks: {
+  permissionRequest: async () => ({ allow: true }),
+}
+```
+
+If you need both, use:
+- `preToolUse` to rewrite tool arguments/tool call
+- `permissionRequest` to allow or block execution
+
 ## 📦 Installation
 
 ```bash
@@ -360,8 +387,9 @@ const agent = new Agent({
   model,
   tools, // Optional: ToolRegistry instance
   stateStore, // Optional: for persistence
-  maxIterations: 5, // Optional: max loop iterations
-  maxConcurrentToolCalls: 5, // Optional: parallel tool calls
+  middleware: [], // Optional: middlewares to register on startup
+  mcpServers: [], // Optional: MCP server configs
+  enableLogging: false, // Optional: internal logs
 })
 ```
 
@@ -369,14 +397,15 @@ const agent = new Agent({
 
 ```typescript
 interface AgentOptions {
+  id?: string // Optional custom agent ID
   name: string // Agent name
   systemPrompt: string // System instructions
-  model: ModelClient | ModelRef // LLM client or reference
+  model: ModelClient // LLM client
   tools?: ToolRegistry // Tool registry (not an array)
   stateStore?: StateStore // Persistence layer
-  maxIterations?: number // Max agent loop iterations (default: 5)
-  maxConcurrentToolCalls?: number // Max parallel tool calls (default: 5)
-  modelSwapWhitelist?: string[] // Allowed model IDs for runtime switching
+  middleware?: Middleware[] // Optional middleware list
+  mcpServers?: MCPServerConfig[] // Optional MCP server configs
+  enableLogging?: boolean // Internal debug logs
 }
 ```
 
@@ -384,10 +413,11 @@ interface AgentOptions {
 
 ```typescript
 // Pin to specific model
-agent.setModel('gpt-4o-mini')
+agent.setModel({ provider: 'openai', modelId: 'gpt-4o-mini' })
 
-// Allow model to switch back
-agent.setModel({ type: 'ref', ref: 'the-model' })
+// Switch to another concrete model client instance
+const otherModelClient = createModel({ adapter: createOpenAIAdapter({ defaultModelId: 'gpt-4o' }) })
+agent.setModel(otherModelClient)
 ```
 
 ### Session Manager
@@ -411,7 +441,23 @@ await sessionManager.destroy('session-id')
 
 ### Using Built-in Tools
 
-GoatChain includes 23 built-in tools:
+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 |
 
 ```typescript
 import {
@@ -490,6 +536,7 @@ const OUTPUT_DIR = path.resolve(import.meta.dirname, 'output')
 const tools = new ToolRegistry()
 tools.register(new ReadTool({ cwd: OUTPUT_DIR }))
 tools.register(new WriteTool({ cwd: OUTPUT_DIR }))
+tools.register(new EditTool({ cwd: OUTPUT_DIR }))
 tools.register(new GlobTool({ cwd: OUTPUT_DIR }))
 tools.register(new GrepTool({ cwd: OUTPUT_DIR }))
 tools.register(new BashTool({ cwd: OUTPUT_DIR }))
@@ -511,6 +558,17 @@ 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`, `readOnlyPaths`, `fileBlacklist`, `disableBlacklist` |
+| `EditTool` | Replaces `old_string` with `new_string` in a file | Relative `file_path` resolves from `cwd` | `file_path` can be absolute | `readOnlyPaths`, `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 | `readOnlyPaths` |
+
 **Directory Configuration Options:**
 
 | Option             | Description                                                         | Example                               |
@@ -587,44 +645,60 @@ const openaiTools = registry.toOpenAIFormat()
 
 ## 🎣 Tool Approval & Hooks
 
-Sessions support lifecycle hooks that let you intercept tool calls for approval, logging, or custom logic.
+Sessions support lifecycle hooks that let you intercept user input, tool calls, and session/subagent lifecycle events.
 
 ### Key Concepts
 
-GoatChain has two separate mechanisms for controlling tool execution:
+GoatChain has three relevant mechanisms for tool execution control:
 
-1. **preToolUse Hook** - For programmatic auto-approval/blocking
-   - `allow: true` → Tool executes immediately, **skips approval flow**
-   - `allow: false` → Tool is blocked
+1. **preToolUse Hook** - For tool-call mutation before permission/approval
+   - Can modify tool name/arguments with `modifiedToolCall`
+   - Runs before `permissionRequest`
+
+2. **permissionRequest Hook** - For programmatic auto-approval/blocking
+   - Runs after `preToolUse`, so it sees the modified tool call
+   - `allow: true` → skips approval flow (execution still goes through normal middleware/disabled checks)
+   - `allow: false` → tool is blocked
    - Use this for automated scenarios where you want to programmatically approve/deny tools
 
-2. **Approval System** (via `toolContext.approval`) - For interactive user approval
+3. **Approval System** (via `toolContext.approval`) - For interactive user approval
    - Pauses execution on high-risk tools
    - Shows `requires_action` event
    - Resumes with user's approval decisions
    - Use this for interactive UIs where users manually approve tools
 
-**These are independent**: If you use `preToolUse` with `allow: true`, the approval system is bypassed entirely.
+**These are independent**: If `permissionRequest` returns `allow: true`, the approval system is bypassed.
 
 ### Hook Types
 
 ```typescript
-interface ToolHooks {
-  // Called before tool execution
-  // - If allow: true, tool executes immediately and skips approval flow
-  // - If allow: false, tool is blocked
+interface AgentHooks {
+  // Session lifecycle
+  sessionStart?: (ctx: SessionStartContext) => Promise<void>
+  sessionEnd?: (ctx: SessionEndContext) => Promise<void>
+  stop?: (ctx: StopContext) => Promise<void>
+  userPromptSubmit?: (ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>
+
+  // Tool lifecycle
   // - Can modify tool call with modifiedToolCall
-  preToolUse?: (ctx: HookContext) => Promise<PreToolUseResult>
+  preToolUse?: (ctx: ToolHookContext) => Promise<PreToolUseResult | void>
+  permissionRequest?: (ctx: ToolHookContext) => Promise<PermissionRequestResult>
+  postToolUse?: (ctx: ToolHookContext, result: unknown) => Promise<void>
+  postToolUseFailure?: (ctx: ToolHookContext, error: Error) => Promise<void>
+
+  // Subagent lifecycle (used by parallel task/subagent middleware)
+  subagentStart?: (ctx: SubagentStartContext) => Promise<void>
+  subagentStop?: (ctx: SubagentStopContext) => Promise<void>
+}
 
-  // Called after successful tool execution
-  postToolUse?: (ctx: HookContext, result: unknown) => Promise<void>
+// Backward-compatible alias
+type ToolHooks = AgentHooks
 
-  // Called after tool execution failure
-  postToolUseFailure?: (ctx: HookContext, error: Error) => Promise<void>
+interface BaseHookContext {
+  sessionId: string
 }
 
-interface HookContext {
-  sessionId: string
+interface ToolHookContext extends BaseHookContext {
   toolCall: {
     id: string
     type: 'function'
@@ -636,15 +710,94 @@ interface HookContext {
   toolContext: ToolExecutionContext
 }
 
-interface PreToolUseResult {
-  // If true, allows tool to execute and skips approval flow
+// `HookContext` is kept as a backward-compatible alias of ToolHookContext
+type HookContext = ToolHookContext
+
+interface PermissionRequestResult {
+  // If true, passes permission checks and skips approval flow
+  // (tool still goes through normal middleware/disabled checks)
   // If false, blocks tool execution immediately
   allow: boolean
   // Optional: Modify the tool call before execution
   modifiedToolCall?: ToolCall
 }
+
+interface PreToolUseResult {
+  // Optional: Modify the tool call before permission/approval/execution
+  modifiedToolCall?: ToolCall
+}
+
+interface UserPromptSubmitResult {
+  allow: boolean
+  modifiedInput?: MessageContent
+}
+
+interface SessionStartContext extends BaseHookContext {
+  startReason: 'new' | 'resume'
+  messages: Message[]
+}
+
+interface StopContext extends BaseHookContext {
+  stopReason:
+    | 'max_iterations'
+    | 'final_response'
+    | 'error'
+    | 'cancelled'
+    | 'approval_required'
+    | 'max_follow_ups'
+  // Stop reason reported by the latest model response, when available
+  // (e.g. 'tool_call' | 'final' | 'length' | 'error' | 'cancelled')
+  modelStopReason?: 'tool_call' | 'final' | 'length' | 'error' | 'cancelled'
+  finalResponse?: string
+  usage: Usage
+  error?: { code?: string; message: string }
+  messages: Message[]
+}
+
+interface SessionEndContext extends BaseHookContext {
+  stopReason: StopContext['stopReason']
+  finalResponse?: string
+  usage: Usage
+  durationMs: number
+  error?: { code?: string; message: string }
+  messages: Message[]
+}
+
+interface UserPromptSubmitContext extends BaseHookContext {
+  input: MessageContent
+}
+
+interface SubagentStartContext extends BaseHookContext {
+  subagentId: string
+  subagentType: string
+  taskDescription?: string
+  prompt: string
+}
+
+interface SubagentStopContext extends BaseHookContext {
+  subagentId: string
+  subagentType: string
+  result?: unknown
+  error?: Error
+  durationMs: number
+  usage?: Usage
+  messages: Message[]
+}
 ```
 
+### Hook Execution Order
+
+Typical order in one run:
+
+1. `sessionStart` (once, on the first `receive()` for this session)
+2. `userPromptSubmit` (before a user message enters the loop; can block or rewrite input)
+3. `preToolUse` (runs first for each tool call; can rewrite tool call)
+4. `permissionRequest` (runs after `preToolUse`; allow/block decision before approval check)
+5. Approval flow (`toolContext.approval`) if still required
+6. `postToolUse` or `postToolUseFailure`
+7. `stop` (after each LLM response completes; for no-LLM termination points, it runs before `done`)
+8. `sessionEnd` (when a run fully finishes; not emitted at `approval_required` pause)
+
 ### Basic Hook Usage
 
 ```typescript
@@ -661,10 +814,17 @@ const agent = new Agent({
 const session = await agent.createSession({
   hooks: {
     preToolUse: async (ctx) => {
+      // Pre-mutate tool call before permission/approval
+      const toolName = ctx.toolCall.function.name
+      console.log(`PreToolUse: ${toolName}`)
+    },
+
+    permissionRequest: async (ctx) => {
       const toolName = ctx.toolCall.function.name
       console.log(`Tool requested: ${toolName}`)
 
-      // Returning { allow: true } skips approval flow and executes tool immediately
+      // Returning { allow: true } skips approval flow
+      // (tool still goes through normal middleware/disabled checks before execution)
       // Returning { allow: false } blocks tool execution
       return { allow: true }
     },
@@ -680,9 +840,9 @@ const session = await agent.createSession({
 })
 ```
 
-### Auto-Approval with preToolUse Hook
+### Auto-Approval with permissionRequest Hook
 
-The `preToolUse` hook is powerful because `allow: true` **bypasses the approval flow entirely**, even for high-risk tools. This is useful for automated scenarios:
+The `permissionRequest` hook is powerful because `allow: true` **bypasses the approval flow entirely**, even for high-risk tools. This is useful for automated scenarios:
 
 ```typescript
 import type { RiskLevel } from 'goatchain'
@@ -706,7 +866,7 @@ function shouldAutoApprove(toolName: string, riskLevel: RiskLevel): boolean {
 
 const session = await agent.createSession({
   hooks: {
-    preToolUse: async (ctx) => {
+    permissionRequest: async (ctx) => {
       const tool = agent.tools.get(ctx.toolCall.function.name)
       const riskLevel = tool?.riskLevel ?? 'safe'
       const allow = shouldAutoApprove(ctx.toolCall.function.name, riskLevel)
@@ -769,12 +929,12 @@ session.send('Your task', {
 
 ### Interactive Approval with Pause/Resume
 
-**Important**: The `preToolUse` hook with `allow: true` **skips approval**. For interactive approval flows where you want to pause and ask the user, use `toolContext.approval` instead:
+**Important**: The `permissionRequest` hook with `allow: true` **skips approval**. For interactive approval flows where you want to pause and ask the user, use `toolContext.approval` instead:
 
 ```typescript
 import type { AgentLoopCheckpoint } from 'goatchain'
 
-// Step 1: Start session WITHOUT preToolUse hook (to use approval system)
+// Step 1: Start session WITHOUT permissionRequest hook (to use approval system)
 const session = await agent.createSession()
 
 let checkpoint: AgentLoopCheckpoint | undefined
@@ -872,12 +1032,9 @@ const session = await agent.createSession({
         }
 
         return {
-          allow: true,
           modifiedToolCall,
         }
       }
-
-      return { allow: true }
     },
   },
 })
@@ -946,7 +1103,7 @@ Adds planning phase before execution:
 ```typescript
 import { createPlanModeMiddleware } from 'goatchain'
 
-// Automatically named 'plan-mode'
+// Automatically named 'plan_mode'
 agent.use(createPlanModeMiddleware())
 
 // With custom configuration
@@ -965,7 +1122,7 @@ Automatically compresses context when token limit is reached using a two-stage s
 ```typescript
 import { createContextCompressionMiddleware } from 'goatchain'
 
-// Automatically named 'context-compression'
+// Automatically named 'context_compression'
 agent.use(
   createContextCompressionMiddleware({
     maxTokens: 128000,
@@ -1597,22 +1754,22 @@ new Agent(options: AgentOptions)
 
 - `name: string` - Agent name (required)
 - `systemPrompt: string` - System instructions (required)
-- `model: ModelClient | ModelRef` - LLM client (required)
+- `model: ModelClient` - LLM client (required)
 - `tools?: ToolRegistry` - Tool registry (not an array)
 - `stateStore?: StateStore` - Persistence layer
-- `maxIterations?: number` - Max loop iterations (default: 5)
-- `maxConcurrentToolCalls?: number` - Max parallel tools (default: 5)
-- `modelSwapWhitelist?: string[]` - Allowed model IDs
+- `middleware?: Middleware[]` - Middleware list to register at startup
+- `mcpServers?: MCPServerConfig[]` - MCP server configuration list
+- `enableLogging?: boolean` - Enable internal logs
 
 #### Methods
 
-**`createSession(options?): Promise<BaseSession>`**
+**`createSession(options?): Promise<Session>`**
 
 Create a new session.
 
 ```typescript
 const session = await agent.createSession({
-  id: 'custom-id', // Optional custom ID
+  sessionId: 'custom-id', // Optional custom session ID
   maxIterations: 10, // Optional max iterations
   requestParams: {
     // Optional request parameters
@@ -1622,7 +1779,7 @@ const session = await agent.createSession({
 })
 ```
 
-**`resumeSession(sessionId, options?): Promise<BaseSession>`**
+**`resumeSession(sessionId, options?): Promise<Session>`**
 
 Resume an existing session from checkpoint.
 
@@ -1630,21 +1787,21 @@ Resume an existing session from checkpoint.
 const session = await agent.resumeSession('session-123')
 ```
 
-**`use(middleware, name?): () => void`**
+**`use(middleware, name?): Promise<() => void>`**
 
 Add middleware. Returns unsubscribe function.
 
 ```typescript
-const unsubscribe = agent.use(myMiddleware, 'my-middleware')
+const unsubscribe = await agent.use(myMiddleware, 'my_middleware')
 unsubscribe() // Remove middleware
 ```
 
-**`removeMiddleware(name): boolean`**
+**`removeMiddleware(nameOrFn): boolean`**
 
-Remove middleware by name.
+Remove middleware by name or function reference.
 
 ```typescript
-agent.removeMiddleware('my-middleware')
+agent.removeMiddleware('my_middleware')
 ```
 
 **`setModel(modelOrRef): void`**
@@ -1652,11 +1809,7 @@ agent.removeMiddleware('my-middleware')
 Switch or pin model at runtime.
 
 ```typescript
-// Pin to specific model
-agent.setModel('gpt-4o-mini')
-
-// Use dynamic reference
-agent.setModel({ type: 'ref', ref: 'the-model' })
+agent.setModel({ provider: 'openai', modelId: 'gpt-4o-mini' })
 ```
 
 #### Properties
@@ -1665,11 +1818,10 @@ agent.setModel({ type: 'ref', ref: 'the-model' })
 - `name: string` - Agent name
 - `systemPrompt: string` - System prompt
 - `model: ModelClient` - Current model client
-- `tools: ToolRegistry` - Tool registry
+- `tools?: ToolRegistry` - Tool registry
 - `stateStore?: StateStore` - State store
-- `sessionManager: BaseSessionManager` - Session manager
+- `sessionManager?: BaseSessionManager` - Session manager
 - `middlewareNames: string[]` - List of middleware names
-- `stats: AgentStats` - Usage statistics
 
 ### Session Class
 
@@ -1802,15 +1954,20 @@ interface ToolCallStartEvent {
 
 interface ToolResultEvent {
   type: 'tool_result'
-  id: string
-  name: string
+  tool_call_id: string
   result: unknown
-  error?: string
+  isError?: boolean
 }
 
 interface DoneEvent {
   type: 'done'
-  stopReason: 'stop' | 'max_iterations' | 'error' | 'cancel'
+  stopReason:
+    | 'max_iterations'
+    | 'final_response'
+    | 'error'
+    | 'cancelled'
+    | 'approval_required'
+    | 'max_follow_ups'
   usage?: Usage
 }
 ```
@@ -1826,12 +1983,12 @@ classDiagram
         +name: string
         +systemPrompt: string
         +model: ModelClient
-        +tools: ToolRegistry
-        +stateStore: StateStore
-        +sessionManager: BaseSessionManager
-        +use(middleware): this
-        +createSession(): Promise~BaseSession~
-        +resumeSession(id): Promise~BaseSession~
+        +tools: ToolRegistry?
+        +stateStore: StateStore?
+        +sessionManager: BaseSessionManager?
+        +use(middleware): Promise~function~
+        +createSession(): Promise~Session~
+        +resumeSession(id): Promise~Session~
     }
 
     class ModelClient {

package/dist/agent/agent.d.ts

@@ -115,17 +115,17 @@ export declare class Agent {
      * }, 'logging');
      *
      * // Built-in middleware with default name
-     * await agent.use(createContextCompressionMiddleware({ ... })); // auto-named 'context-compression'
+     * await agent.use(createContextCompressionMiddleware({ ... })); // auto-named 'context_compression'
      *
      * // Override default name
-     * await agent.use(createPlanModeMiddleware(), 'my-plan-mode');
+     * await agent.use(createPlanModeMiddleware(), 'my_plan_mode');
      *
      * // Middleware with tools (auto-registers tools with namespace)
      * const middleware: Middleware = async (state, next) => next(state);
-     * middleware.__middlewareName = 'plan-mode';
+     * middleware.__middlewareName = 'plan_mode';
      * middleware.__createTools = async () => [new EnterPlanModeTool()];
      * await agent.use(middleware);
-     * // Tool registered as: 'plan-mode_EnterPlanMode'
+     * // Tool registered as: 'plan_mode_EnterPlanMode'
      *
      * // Anonymous middleware (auto-named)
      * const unsubscribe = await agent.use(async (state, next) => {

package/dist/agent/hooks/index.d.ts

@@ -1,2 +1,2 @@
 export { HookManager } from './manager';
-export type { HookContext, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, ToolHooks, } from './types';
+export type { AgentHooks, BaseHookContext, HookContext, PermissionRequestHook, PermissionRequestResult, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, SessionEndContext, SessionEndHook, SessionStartContext, SessionStartHook, StopContext, StopHook, SubagentStartContext, SubagentStartHook, SubagentStopContext, SubagentStopHook, ToolHookContext, ToolHooks, UserPromptSubmitContext, UserPromptSubmitHook, UserPromptSubmitResult, } from './types';

package/dist/agent/hooks/manager.d.ts

@@ -1,8 +1,15 @@
-import type { HookContext, PreToolUseResult, ToolHooks } from './types';
+import type { AgentHooks, HookContext, PermissionRequestResult, PreToolUseResult, SessionEndContext, SessionStartContext, SubagentStartContext, StopContext, SubagentStopContext, UserPromptSubmitContext, UserPromptSubmitResult } from './types';
 export declare class HookManager {
     private readonly hooks;
-    constructor(hooks?: ToolHooks);
-    executePreToolUse(context: HookContext): Promise<PreToolUseResult>;
+    constructor(hooks?: AgentHooks);
+    executePermissionRequest(context: HookContext): Promise<PermissionRequestResult>;
+    executePreToolUse(context: HookContext): Promise<PreToolUseResult | void>;
+    executeUserPromptSubmit(context: UserPromptSubmitContext): Promise<UserPromptSubmitResult>;
+    executeSessionStart(context: SessionStartContext): Promise<void>;
+    executeSessionEnd(context: SessionEndContext): Promise<void>;
     executePostToolUse(context: HookContext, result: unknown): Promise<void>;
     executePostToolUseFailure(context: HookContext, error: Error): Promise<void>;
+    executeStop(context: StopContext): Promise<void>;
+    executeSubagentStart(context: SubagentStartContext): Promise<void>;
+    executeSubagentStop(context: SubagentStopContext): Promise<void>;
 }