fix: gracefully recover from bad model names in subagents

If the requested model fails (bad name, unsupported provider), fall back to the parent's model instead of returning a hard error. The original prompt is prepended with a note so the agent knows which model is actually running and can adjust future calls.
fix: inherit parent provider for bare model names in subagents
2026-06-18 21:36:30 +00:00 · 2026-03-16 13:43:52 +03:00 · 2026-03-16 13:41:02 +03:00 · 2026-03-16 13:06:53 +03:00 · 2026-03-16 13:01:34 +03:00 · 2026-03-16 11:39:59 +03:00
29 changed files with 2947 additions and 116 deletions
@@ -0,0 +1,853 @@
+---
+name: kit-extensions
+description: Guide for creating Kit extensions. Use when the user asks to build, create, or modify a Kit extension, add a custom tool, slash command, widget, keyboard shortcut, editor interceptor, tool renderer, or hook into any Kit lifecycle event.
+---
+
+# Kit Extensions Development Guide
+
+Kit extensions are single-file Go programs interpreted at runtime by Yaegi. They hook into Kit's lifecycle, register custom tools and slash commands, display widgets, intercept editor input, render tool output, and more.
+
+## Extension Structure
+
+Every extension must export a `package main` with an `Init(api ext.API)` function:
+
+```go
+//go:build ignore
+
+package main
+
+import "kit/ext"
+
+func Init(api ext.API) {
+    // Register event handlers, tools, commands, etc.
+}
+```
+
+The `//go:build ignore` tag prevents `go build` from compiling the file directly.
+
+## Extension Locations
+
+Extensions are auto-loaded from these directories:
+
+- `~/.config/kit/extensions/*.go` (global, single files)
+- `~/.config/kit/extensions/*/main.go` (global, subdirectories)
+- `.kit/extensions/*.go` (project-local, single files)
+- `.kit/extensions/*/main.go` (project-local, subdirectories)
+
+Or loaded explicitly:
+
+```bash
+kit -e path/to/extension.go
+kit --extension path/to/extension.go
+```
+
+## Import Path
+
+Extensions import the Kit API as `"kit/ext"`. The full standard library is available plus `os/exec` for subprocess spawning.
+
+## API Overview
+
+The `Init` function receives an `ext.API` object for registering handlers, and event handlers receive an `ext.Context` with runtime capabilities.
+
+---
+
+## Lifecycle Events
+
+Kit provides 18 lifecycle events. Each handler receives an event struct and a `Context`.
+
+### Session Events
+
+```go
+// Fired when session is loaded/created.
+api.OnSessionStart(func(e ext.SessionStartEvent, ctx ext.Context) {
+    // e.SessionID string
+})
+
+// Fired when Kit is shutting down. Use for cleanup.
+api.OnSessionShutdown(func(e ext.SessionShutdownEvent, ctx ext.Context) {
+    // No fields.
+})
+```
+
+### Agent Turn Events
+
+```go
+// Before agent starts processing. Can inject system prompt or text.
+api.OnBeforeAgentStart(func(e ext.BeforeAgentStartEvent, ctx ext.Context) *ext.BeforeAgentStartResult {
+    // e.Prompt string
+    // Return nil to pass through.
+    // Return &ext.BeforeAgentStartResult{SystemPrompt: &s} to augment system prompt.
+    // Return &ext.BeforeAgentStartResult{InjectText: &s} to inject text before prompt.
+    return nil
+})
+
+// Agent loop has started.
+api.OnAgentStart(func(e ext.AgentStartEvent, ctx ext.Context) {
+    // e.Prompt string
+})
+
+// Agent finished responding.
+api.OnAgentEnd(func(e ext.AgentEndEvent, ctx ext.Context) {
+    // e.Response string
+    // e.StopReason string — "completed", "cancelled", "error"
+})
+```
+
+### Tool Events
+
+```go
+// Before a tool executes. Can block the call.
+api.OnToolCall(func(e ext.ToolCallEvent, ctx ext.Context) *ext.ToolCallResult {
+    // e.ToolName string
+    // e.ToolCallID string
+    // e.Input string — JSON-encoded parameters
+    // e.Source string — "llm" or "user"
+    // Return nil to allow.
+    // Return &ext.ToolCallResult{Block: true, Reason: "..."} to block.
+    return nil
+})
+
+// Tool execution started (informational only).
+api.OnToolExecutionStart(func(e ext.ToolExecutionStartEvent, ctx ext.Context) {
+    // e.ToolName string
+})
+
+// Tool execution ended (informational only).
+api.OnToolExecutionEnd(func(e ext.ToolExecutionEndEvent, ctx ext.Context) {
+    // e.ToolName string
+})
+
+// After a tool returns. Can modify the result.
+api.OnToolResult(func(e ext.ToolResultEvent, ctx ext.Context) *ext.ToolResultResult {
+    // e.ToolName string
+    // e.Input string
+    // e.Content string
+    // e.IsError bool
+    // Return nil to pass through.
+    // Return &ext.ToolResultResult{Content: &s} to replace content.
+    // Return &ext.ToolResultResult{IsError: &b} to change error status.
+    return nil
+})
+```
+
+### Input Events
+
+```go
+// User submitted input. Can handle or transform it.
+api.OnInput(func(e ext.InputEvent, ctx ext.Context) *ext.InputResult {
+    // e.Text string
+    // e.Source string — "interactive", "cli", "script", "queue"
+    // Return nil to pass through to agent.
+    // Return &ext.InputResult{Action: "handled"} to consume without sending to agent.
+    // Return &ext.InputResult{Action: "transform", Text: "new text"} to rewrite.
+    return nil
+})
+```
+
+### Streaming Events
+
+```go
+api.OnMessageStart(func(e ext.MessageStartEvent, ctx ext.Context) {})
+api.OnMessageUpdate(func(e ext.MessageUpdateEvent, ctx ext.Context) {
+    // e.Chunk string — streaming text chunk
+})
+api.OnMessageEnd(func(e ext.MessageEndEvent, ctx ext.Context) {
+    // e.Content string — full message content
+})
+```
+
+### Model Events
+
+```go
+api.OnModelChange(func(e ext.ModelChangeEvent, ctx ext.Context) {
+    // e.NewModel string
+    // e.PreviousModel string
+    // e.Source string — "extension" or "user"
+})
+```
+
+### Context Filtering
+
+```go
+// Before messages are sent to the LLM. Can filter, reorder, or inject messages.
+api.OnContextPrepare(func(e ext.ContextPrepareEvent, ctx ext.Context) *ext.ContextPrepareResult {
+    // e.Messages []ext.ContextMessage
+    // Each ContextMessage has: Index int, Role string, Content string
+    // Index -1 means a new injected message (not from session).
+    // Return nil to pass through.
+    // Return &ext.ContextPrepareResult{Messages: msgs} to replace the context window.
+    return nil
+})
+```
+
+### Session Control Events
+
+```go
+// Before forking the session tree. Can cancel.
+api.OnBeforeFork(func(e ext.BeforeForkEvent, ctx ext.Context) *ext.BeforeForkResult {
+    // e.TargetID string, e.IsUserMessage bool, e.UserText string
+    return nil // or &ext.BeforeForkResult{Cancel: true, Reason: "..."}
+})
+
+// Before switching/clearing session. Can cancel.
+api.OnBeforeSessionSwitch(func(e ext.BeforeSessionSwitchEvent, ctx ext.Context) *ext.BeforeSessionSwitchResult {
+    // e.Reason string — "new" or "clear"
+    return nil // or &ext.BeforeSessionSwitchResult{Cancel: true, Reason: "..."}
+})
+
+// Before context compaction. Can cancel.
+api.OnBeforeCompact(func(e ext.BeforeCompactEvent, ctx ext.Context) *ext.BeforeCompactResult {
+    // e.EstimatedTokens, e.ContextLimit int
+    // e.UsagePercent float64, e.MessageCount int, e.IsAutomatic bool
+    return nil // or &ext.BeforeCompactResult{Cancel: true, Reason: "..."}
+})
+```
+
+### Custom Events
+
+```go
+// Subscribe to custom events emitted by other extensions.
+api.OnCustomEvent("event-name", func(data string) {
+    // data is arbitrary string payload
+})
+
+// Emit from Context:
+ctx.EmitCustomEvent("event-name", "payload")
+```
+
+---
+
+## Registering Tools
+
+Tools are functions the LLM can invoke:
+
+```go
+api.RegisterTool(ext.ToolDef{
+    Name:        "current_time",
+    Description: "Get the current date and time",
+    Parameters:  `{"type":"object","properties":{}}`,
+    Execute: func(input string) (string, error) {
+        return time.Now().Format(time.RFC3339), nil
+    },
+})
+```
+
+For long-running tools with cancellation and progress:
+
+```go
+api.RegisterTool(ext.ToolDef{
+    Name:        "slow_task",
+    Description: "A long-running task with progress reporting",
+    Parameters:  `{"type":"object","properties":{"query":{"type":"string"}}}`,
+    ExecuteWithContext: func(input string, tc ext.ToolContext) (string, error) {
+        for i := 0; i < 10; i++ {
+            if tc.IsCancelled() {
+                return "cancelled", nil
+            }
+            tc.OnProgress(fmt.Sprintf("Step %d/10...", i+1))
+            time.Sleep(time.Second)
+        }
+        return "done", nil
+    },
+})
+```
+
+Parameters must be a JSON Schema string. The `input` argument is the JSON-encoded parameters from the LLM.
+
+---
+
+## Registering Slash Commands
+
+Commands are user-facing actions invoked with `/name` in the input:
+
+```go
+api.RegisterCommand(ext.CommandDef{
+    Name:        "echo",
+    Description: "Echo back the provided text",
+    Execute: func(args string, ctx ext.Context) (string, error) {
+        ctx.PrintInfo("You said: " + args)
+        return "", nil
+    },
+    // Optional tab-completion:
+    Complete: func(prefix string, ctx ext.Context) []string {
+        return []string{"hello", "world"}
+    },
+})
+```
+
+Slash commands run in a dedicated goroutine (not a `tea.Cmd`), so they can safely block on prompts, I/O, etc.
+
+---
+
+## Registering Keyboard Shortcuts
+
+```go
+api.RegisterShortcut(ext.ShortcutDef{
+    Key:         "ctrl+alt+p",
+    Description: "Toggle plan mode",
+}, func(ctx ext.Context) {
+    // handler runs when shortcut is pressed
+})
+```
+
+---
+
+## Registering Options
+
+Options are configurable values resolved from env vars, config, or defaults:
+
+```go
+api.RegisterOption(ext.OptionDef{
+    Name:        "my-setting",
+    Description: "Controls something",
+    Default:     "false",
+})
+
+// Read at runtime (resolution: env KIT_OPT_MY_SETTING > config options.my-setting > default):
+val := ctx.GetOption("my-setting")
+
+// Set at runtime:
+ctx.SetOption("my-setting", "true")
+```
+
+---
+
+## Context API Reference
+
+The `ext.Context` struct provides runtime capabilities via function fields.
+
+### Output
+
+```go
+ctx.Print("plain text")                    // plain output
+ctx.PrintInfo("styled info block")         // bordered info block
+ctx.PrintError("styled error block")       // red error block
+ctx.PrintBlock(ext.PrintBlockOpts{         // custom styled block
+    Text:        "content",
+    BorderColor: "#a6e3a1",
+    Subtitle:    "my-ext",
+})
+ctx.RenderMessage("renderer-name", "content")  // use a registered message renderer
+```
+
+### Message Injection
+
+```go
+ctx.SendMessage("prompt text")     // inject message and trigger agent turn (queued)
+ctx.CancelAndSend("new prompt")   // cancel current turn, clear queue, send new message
+```
+
+### Widgets
+
+Persistent UI elements displayed above or below the input area:
+
+```go
+ctx.SetWidget(ext.WidgetConfig{
+    ID:        "my-widget",
+    Placement: ext.WidgetAbove,  // or ext.WidgetBelow
+    Content:   ext.WidgetContent{
+        Text:     "Status: Active",
+        Markdown: false,  // set true for markdown rendering
+    },
+    Style: ext.WidgetStyle{
+        BorderColor: "#a6e3a1",  // hex color
+        NoBorder:    false,
+    },
+    Priority: 0,  // lower values render first
+})
+
+ctx.RemoveWidget("my-widget")
+```
+
+### Header and Footer
+
+```go
+ctx.SetHeader(ext.HeaderFooterConfig{
+    Content: ext.WidgetContent{Text: "My Header"},
+    Style:   ext.WidgetStyle{BorderColor: "#89b4fa"},
+})
+ctx.RemoveHeader()
+
+ctx.SetFooter(ext.HeaderFooterConfig{
+    Content: ext.WidgetContent{Text: "My Footer"},
+    Style:   ext.WidgetStyle{BorderColor: "#585b70"},
+})
+ctx.RemoveFooter()
+```
+
+### Status Bar
+
+```go
+ctx.SetStatus("key", "PLAN MODE", 10)  // key, text, priority (lower = further left)
+ctx.RemoveStatus("key")
+```
+
+### Interactive Prompts
+
+These block until the user responds (safe in slash commands and goroutines):
+
+```go
+// Selection list
+result := ctx.PromptSelect(ext.PromptSelectConfig{
+    Message: "Pick one:",
+    Options: []string{"Option A", "Option B", "Option C"},
+})
+if !result.Cancelled {
+    // result.Value string, result.Index int
+}
+
+// Yes/No confirmation
+result := ctx.PromptConfirm(ext.PromptConfirmConfig{
+    Message:      "Are you sure?",
+    DefaultValue: false,
+})
+if !result.Cancelled {
+    // result.Value bool
+}
+
+// Text input
+result := ctx.PromptInput(ext.PromptInputConfig{
+    Message:     "Enter name:",
+    Placeholder: "my-project",
+    Default:     "",
+})
+if !result.Cancelled {
+    // result.Value string
+}
+```
+
+### Overlay Dialogs
+
+Modal dialogs with optional action buttons:
+
+```go
+result := ctx.ShowOverlay(ext.OverlayConfig{
+    Title:   "Confirmation",
+    Content: ext.WidgetContent{Text: "Are you sure you want to proceed?", Markdown: true},
+    Style:   ext.OverlayStyle{BorderColor: "#f38ba8"},
+    Width:   60,          // 0 = 60% of terminal width
+    MaxHeight: 20,        // 0 = 80% of terminal height
+    Anchor:  ext.OverlayCenter,  // or ext.OverlayTopCenter, ext.OverlayBottomCenter
+    Actions: []string{"Confirm", "Cancel"},
+})
+if !result.Cancelled {
+    // result.Action string, result.Index int
+}
+```
+
+### Editor Interceptor
+
+Wrap the built-in text input with custom key handling and rendering:
+
+```go
+ctx.SetEditor(ext.EditorConfig{
+    HandleKey: func(key string, currentText string) ext.EditorKeyAction {
+        if key == "ctrl+s" {
+            return ext.EditorKeyAction{Type: ext.EditorKeySubmit, SubmitText: currentText}
+        }
+        return ext.EditorKeyAction{Type: ext.EditorKeyPassthrough}
+    },
+    Render: func(width int, defaultContent string) string {
+        return "[custom] " + defaultContent
+    },
+})
+
+ctx.ResetEditor()                  // remove interceptor
+ctx.SetEditorText("prefilled")     // set editor text content
+```
+
+**EditorKeyAction types:**
+- `ext.EditorKeyPassthrough` — let the default editor handle the key
+- `ext.EditorKeyConsumed` — swallow the key, do nothing
+- `ext.EditorKeyRemap` — remap to a different key: `EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "up"}`
+- `ext.EditorKeySubmit` — submit text: `EditorKeyAction{Type: ext.EditorKeySubmit, SubmitText: "text"}`
+
+### UI Visibility
+
+```go
+ctx.SetUIVisibility(ext.UIVisibility{
+    HideStartupMessage: true,
+    HideStatusBar:      true,
+    HideSeparator:      true,
+    HideInputHint:      true,
+})
+```
+
+### Session Data
+
+```go
+stats := ctx.GetContextStats()     // .EstimatedTokens, .ContextLimit, .UsagePercent, .MessageCount
+msgs := ctx.GetMessages()          // []ext.SessionMessage on current branch
+path := ctx.GetSessionPath()       // file path of session JSONL
+
+// Persist custom data in the session tree:
+id, err := ctx.AppendEntry("my-type", "data string")
+entries := ctx.GetEntries("my-type")  // []ext.ExtensionEntry{ID, EntryType, Data, Timestamp}
+```
+
+### Model Management
+
+```go
+err := ctx.SetModel("anthropic/claude-sonnet-4-20250514")
+models := ctx.GetAvailableModels()  // []ext.ModelInfoEntry
+```
+
+### Tool Management
+
+```go
+tools := ctx.GetAllTools()              // []ext.ToolInfo{Name, Description, Source, Enabled}
+ctx.SetActiveTools([]string{"read", "grep"})  // restrict to these tools only
+ctx.SetActiveTools(nil)                 // re-enable all tools
+```
+
+### LLM Completions
+
+Make standalone LLM calls (bypasses the agent tool loop):
+
+```go
+resp, err := ctx.Complete(ext.CompleteRequest{
+    Model:    "",             // empty = current model
+    System:   "You are ...",  // optional system prompt
+    Prompt:   "Summarize...", // the prompt
+    MaxTokens: 1000,          // 0 = provider default
+    OnChunk:  func(chunk string) { /* streaming */ },
+})
+// resp.Text, resp.InputTokens, resp.OutputTokens, resp.Model
+```
+
+### TUI Suspension
+
+Temporarily release the terminal for interactive subprocesses:
+
+```go
+ctx.SuspendTUI(func() {
+    cmd := exec.Command("vim", "file.go")
+    cmd.Stdin = os.Stdin
+    cmd.Stdout = os.Stdout
+    cmd.Stderr = os.Stderr
+    cmd.Run()
+})
+```
+
+### Application Control
+
+```go
+ctx.Exit()                        // graceful shutdown
+err := ctx.ReloadExtensions()     // hot-reload all extensions from disk
+```
+
+### Context Fields
+
+```go
+ctx.SessionID    // string
+ctx.CWD          // string — current working directory
+ctx.Model        // string — active model name
+ctx.Interactive  // bool — true if running in TUI mode
+```
+
+---
+
+## Tool Renderers
+
+Customize how tool calls are displayed in the TUI:
+
+```go
+api.RegisterToolRenderer(ext.ToolRenderConfig{
+    ToolName:     "bash",
+    DisplayName:  "Shell",           // replaces auto-capitalized name
+    BorderColor:  "#89b4fa",
+    Background:   "",
+    BodyMarkdown: true,              // render body through markdown
+    RenderHeader: func(toolArgs string, width int) string {
+        var args struct{ Command string `json:"command"` }
+        json.Unmarshal([]byte(toolArgs), &args)
+        return "$ " + args.Command
+    },
+    RenderBody: func(toolResult string, isError bool, width int) string {
+        if isError {
+            return "ERROR: " + toolResult
+        }
+        return toolResult
+    },
+})
+```
+
+## Message Renderers
+
+Define named output styles for `ctx.RenderMessage()`:
+
+```go
+api.RegisterMessageRenderer(ext.MessageRendererConfig{
+    Name: "success",
+    Render: func(content string, width int) string {
+        return "  " + content  // green checkmark prefix
+    },
+})
+
+// Usage in handlers:
+ctx.RenderMessage("success", "All tests passed")
+```
+
+---
+
+## Critical Yaegi Constraints
+
+### No Named Function References in Struct Fields
+
+Yaegi has a bug where named function references assigned to struct fields return zero values across the interpreter boundary. Always use anonymous closure literals:
+
+```go
+// WRONG - will silently return zero values:
+func myHandler(key, text string) ext.EditorKeyAction {
+    return ext.EditorKeyAction{Type: ext.EditorKeyPassthrough}
+}
+ctx.SetEditor(ext.EditorConfig{HandleKey: myHandler})
+
+// CORRECT - use anonymous closure:
+ctx.SetEditor(ext.EditorConfig{
+    HandleKey: func(key, text string) ext.EditorKeyAction {
+        return ext.EditorKeyAction{Type: ext.EditorKeyPassthrough}
+    },
+})
+```
+
+This applies to ALL struct fields that take function values: `ToolDef.Execute`, `CommandDef.Execute`, `EditorConfig.HandleKey`, `EditorConfig.Render`, `ToolRenderConfig.RenderHeader`, `ToolRenderConfig.RenderBody`, etc.
+
+### No Interfaces Across the Boundary
+
+All extension-facing API types are concrete structs, never interfaces. Yaegi crashes on interface wrapper generation.
+
+### Package-Level Variables for State
+
+Yaegi supports package-level variables captured in closures. This is the standard way to maintain state across event callbacks:
+
+```go
+package main
+
+import "kit/ext"
+
+var callCount int
+var lastTool string
+
+func Init(api ext.API) {
+    api.OnToolResult(func(e ext.ToolResultEvent, ctx ext.Context) *ext.ToolResultResult {
+        callCount++
+        lastTool = e.ToolName
+        return nil
+    })
+}
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Tool Call Blocking
+
+Block dangerous operations by intercepting tool calls:
+
+```go
+api.OnToolCall(func(tc ext.ToolCallEvent, ctx ext.Context) *ext.ToolCallResult {
+    if tc.ToolName == "bash" {
+        var input struct{ Command string `json:"command"` }
+        json.Unmarshal([]byte(tc.Input), &input)
+        if strings.Contains(input.Command, "rm -rf") {
+            return &ext.ToolCallResult{
+                Block:  true,
+                Reason: "Dangerous command blocked",
+            }
+        }
+    }
+    return nil
+})
+```
+
+### Pattern: System Prompt Injection
+
+Augment the agent's behavior by injecting instructions:
+
+```go
+api.OnBeforeAgentStart(func(_ ext.BeforeAgentStartEvent, ctx ext.Context) *ext.BeforeAgentStartResult {
+    prompt := "Always respond with bullet points."
+    return &ext.BeforeAgentStartResult{SystemPrompt: &prompt}
+})
+```
+
+### Pattern: Background Processing with SendMessage
+
+Run work in a goroutine and inject results back:
+
+```go
+api.RegisterCommand(ext.CommandDef{
+    Name: "run",
+    Description: "Run a command in the background",
+    Execute: func(args string, ctx ext.Context) (string, error) {
+        go func() {
+            out, err := exec.Command("sh", "-c", args).CombinedOutput()
+            if err != nil {
+                ctx.SendMessage(fmt.Sprintf("Command failed: %s\n%s", err, out))
+                return
+            }
+            ctx.SendMessage(fmt.Sprintf("Command output:\n```\n%s\n```", out))
+        }()
+        return "Running in background...", nil
+    },
+})
+```
+
+### Pattern: Ephemeral Context Injection
+
+Inject information into every LLM turn without persisting in session history:
+
+```go
+api.OnContextPrepare(func(e ext.ContextPrepareEvent, ctx ext.Context) *ext.ContextPrepareResult {
+    data, err := os.ReadFile(".kit/context.md")
+    if err != nil {
+        return nil
+    }
+    injected := ext.ContextMessage{
+        Index:   -1,  // -1 = new message, not from session
+        Role:    "system",
+        Content: string(data),
+    }
+    msgs := append([]ext.ContextMessage{injected}, e.Messages...)
+    return &ext.ContextPrepareResult{Messages: msgs}
+})
+```
+
+### Pattern: Live Widget Updates
+
+Update a widget periodically from a goroutine:
+
+```go
+api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+    go func() {
+        ticker := time.NewTicker(time.Second)
+        defer ticker.Stop()
+        for range ticker.C {
+            ctx.SetWidget(ext.WidgetConfig{
+                ID:        "clock",
+                Placement: ext.WidgetAbove,
+                Content:   ext.WidgetContent{Text: time.Now().Format("15:04:05")},
+                Style:     ext.WidgetStyle{BorderColor: "#89b4fa"},
+            })
+        }
+    }()
+})
+```
+
+### Pattern: Spawning Kit as a Sub-Agent
+
+Extensions can spawn Kit as a subprocess for delegation:
+
+```bash
+kit --quiet --no-session --no-extensions --system-prompt "You are a reviewer" --model anthropic/claude-sonnet-4-20250514 "Review this code"
+```
+
+Key flags: `--quiet` (stdout only, no TUI), `--no-session` (ephemeral), `--no-extensions` (prevent recursion), `--system-prompt` (string or file path).
+
+---
+
+## Testing Extensions
+
+```bash
+# Validate syntax of all discovered extensions
+kit extensions validate
+
+# List loaded extensions
+kit extensions list
+
+# Run with a specific extension
+kit -e path/to/extension.go
+
+# Run with multiple extensions
+kit -e ext1.go -e ext2.go
+
+# Disable all extensions
+kit --no-extensions
+
+# Generate an example extension scaffold
+kit extensions init
+```
+
+---
+
+## Complete Example: Plan Mode
+
+A full extension that restricts the agent to read-only tools, with a slash command, keyboard shortcut, option, status bar indicator, and system prompt injection:
+
+```go
+//go:build ignore
+
+package main
+
+import (
+    "strings"
+    "kit/ext"
+)
+
+func Init(api ext.API) {
+    readOnlyTools := []string{"read", "grep", "find", "ls"}
+    var planActive bool
+
+    api.RegisterOption(ext.OptionDef{
+        Name:        "plan",
+        Description: "Start in plan mode (read-only tools)",
+        Default:     "false",
+    })
+
+    api.RegisterShortcut(ext.ShortcutDef{
+        Key:         "ctrl+alt+p",
+        Description: "Toggle plan/explore mode",
+    }, func(ctx ext.Context) {
+        planActive = !planActive
+        applyMode(ctx, planActive, readOnlyTools)
+    })
+
+    api.RegisterCommand(ext.CommandDef{
+        Name:        "plan",
+        Description: "Toggle plan/explore mode",
+        Execute: func(args string, ctx ext.Context) (string, error) {
+            planActive = !planActive
+            applyMode(ctx, planActive, readOnlyTools)
+            return "", nil
+        },
+    })
+
+    api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+        if strings.ToLower(ctx.GetOption("plan")) == "true" {
+            planActive = true
+            applyMode(ctx, true, readOnlyTools)
+        }
+    })
+
+    api.OnBeforeAgentStart(func(_ ext.BeforeAgentStartEvent, ctx ext.Context) *ext.BeforeAgentStartResult {
+        if !planActive {
+            return nil
+        }
+        prompt := `You are in PLAN MODE (read-only). You can ONLY read and search.
+Focus on understanding, analysis, and generating plans.`
+        return &ext.BeforeAgentStartResult{SystemPrompt: &prompt}
+    })
+}
+
+func applyMode(ctx ext.Context, active bool, tools []string) {
+    if active {
+        ctx.SetActiveTools(tools)
+        ctx.SetStatus("plan-mode", "PLAN MODE (read-only)", 10)
+        ctx.PrintInfo("Plan mode ON")
+    } else {
+        ctx.SetActiveTools(nil)
+        ctx.RemoveStatus("plan-mode")
+        ctx.PrintInfo("Plan mode OFF")
+    }
+}
+```
+
+## Key Files for Reference
+
+- [`internal/extensions/api.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/api.go) — Complete API type definitions
+- [`internal/extensions/runner.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/runner.go) — Event dispatch and state management
+- [`internal/extensions/loader.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/loader.go) — Yaegi interpreter setup
+- [`internal/extensions/symbols.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/symbols.go) — All types exported to extensions
+- [`examples/extensions/`](https://github.com/mark3labs/kit/tree/main/examples/extensions) — 25+ working example extensions
@@ -925,7 +925,40 @@ func runNormalMode(ctx context.Context) error {
 				}
 			},
 			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
-				return extensions.SpawnSubagent(config)
+				// In-process subagent via SDK.
+				sdkCfg := kit.SubagentConfig{
+					Prompt:       config.Prompt,
+					Model:        config.Model,
+					SystemPrompt: config.SystemPrompt,
+					Timeout:      config.Timeout,
+					NoSession:    config.NoSession,
+				}
+				// Bridge SDK events to extension SubagentEvents.
+				if config.OnEvent != nil {
+					sdkCfg.OnEvent = func(e kit.Event) {
+						se := sdkEventToSubagentEvent(e)
+						if se.Type != "" {
+							config.OnEvent(se)
+						}
+					}
+				}
+				result, err := kitInstance.Subagent(ctx, sdkCfg)
+				if result == nil {
+					return nil, &extensions.SubagentResult{Error: err}, err
+				}
+				extResult := &extensions.SubagentResult{
+					Response:  result.Response,
+					Error:     result.Error,
+					SessionID: result.SessionID,
+					Elapsed:   result.Elapsed,
+				}
+				if result.Usage != nil {
+					extResult.Usage = &extensions.SubagentUsage{
+						InputTokens:  result.Usage.InputTokens,
+						OutputTokens: result.Usage.OutputTokens,
+					}
+				}
+				return nil, extResult, err
 			},
 		})
 		kitInstance.EmitSessionStart()
@@ -1086,15 +1119,19 @@ func buildJSONOutput(result *kit.TurnResult, model string) ([]byte, error) {
 		CacheCreationTokens int64 `json:"cache_creation_tokens"`
 	}
 	type jsonEnvelope struct {
-		Response string        `json:"response"`
-		Model    string        `json:"model"`
-		Usage    *jsonUsage    `json:"usage,omitempty"`
-		Messages []jsonMessage `json:"messages"`
+		Response   string        `json:"response"`
+		Model      string        `json:"model"`
+		StopReason string        `json:"stop_reason,omitempty"`
+		SessionID  string        `json:"session_id,omitempty"`
+		Usage      *jsonUsage    `json:"usage,omitempty"`
+		Messages   []jsonMessage `json:"messages"`
 	}

 	out := jsonEnvelope{
-		Response: result.Response,
-		Model:    model,
+		Response:   result.Response,
+		Model:      model,
+		StopReason: result.StopReason,
+		SessionID:  result.SessionID,
 	}

 	if result.TotalUsage != nil {
@@ -1205,3 +1242,42 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 	_, runErr := program.Run()
 	return runErr
 }
+
+// sdkEventToSubagentEvent converts an SDK event to an extension-facing
+// SubagentEvent. Returns a zero-value event (Type=="") for events that
+// don't map to anything useful.
+func sdkEventToSubagentEvent(e kit.Event) extensions.SubagentEvent {
+	switch ev := e.(type) {
+	case kit.MessageUpdateEvent:
+		return extensions.SubagentEvent{Type: "text", Content: ev.Chunk}
+	case kit.ReasoningDeltaEvent:
+		return extensions.SubagentEvent{Type: "reasoning", Content: ev.Delta}
+	case kit.ToolCallEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_call", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind, ToolArgs: ev.ToolArgs,
+		}
+	case kit.ToolExecutionStartEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_start", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolExecutionEndEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_end", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolResultEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_result", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+			ToolResult: ev.Result, IsError: ev.IsError,
+		}
+	case kit.TurnStartEvent:
+		return extensions.SubagentEvent{Type: "turn_start"}
+	case kit.TurnEndEvent:
+		return extensions.SubagentEvent{Type: "turn_end"}
+	default:
+		return extensions.SubagentEvent{}
+	}
+}
@@ -90,6 +90,7 @@ func (a *Agent) NewSession(ctx context.Context, params acp.NewSessionRequest) (a

 	sess, err := a.registry.create(ctx, cwd)
 	if err != nil {
+		log.Error("acp: session creation failed", "cwd", cwd, "error", err)
 		return acp.NewSessionResponse{}, fmt.Errorf("create session: %w", err)
 	}

@@ -185,7 +186,10 @@ func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.S
 			update = &u

 		case kit.ToolCallEvent:
-			tcID := acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Add(1)))
+			tcID := acp.ToolCallId(ev.ToolCallID)
+			if tcID == "" {
+				tcID = acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Add(1)))
+			}
 			u := acp.StartToolCall(tcID, ev.ToolName,
 				acp.WithStartStatus(acp.ToolCallStatusInProgress),
 				acp.WithStartRawInput(parseToolArgs(ev.ToolArgs)),
@@ -193,7 +197,10 @@ func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.S
 			update = &u

 		case kit.ToolResultEvent:
-			tcID := acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Load()))
+			tcID := acp.ToolCallId(ev.ToolCallID)
+			if tcID == "" {
+				tcID = acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Load()))
+			}
 			status := acp.ToolCallStatusCompleted
 			if ev.IsError {
 				status = acp.ToolCallStatusFailed
@@ -3,8 +3,12 @@ package acpserver
 import (
 	"context"
 	"fmt"
+	"strings"
 	"sync"

+	"github.com/charmbracelet/log"
+
+	"github.com/mark3labs/kit/internal/extensions"
 	kit "github.com/mark3labs/kit/pkg/kit"
 )

@@ -39,6 +43,12 @@ func (r *sessionRegistry) create(ctx context.Context, cwd string) (*acpSession,
 		Streaming:  true,
 	})
 	if err != nil {
+		// Provide actionable guidance for provider auth errors, which are
+		// the most common failure mode when running via ACP.
+		msg := err.Error()
+		if strings.Contains(msg, "API key") || strings.Contains(msg, "credentials") || strings.Contains(msg, "OAuth") {
+			return nil, fmt.Errorf("provider authentication failed: %w — run 'kit auth login <provider>' or set the appropriate environment variable before starting 'kit acp'", err)
+		}
 		return nil, fmt.Errorf("create kit instance: %w", err)
 	}

@@ -48,6 +58,147 @@ func (r *sessionRegistry) create(ctx context.Context, cwd string) (*acpSession,
 		return nil, fmt.Errorf("kit instance has no session ID")
 	}

+	// Wire extension context with headless implementations so extensions
+	// work in ACP mode. TUI-dependent features (widgets, prompts, editor)
+	// become no-ops or return cancelled; all data/model/tool APIs work
+	// identically to interactive mode.
+	if kitInstance.HasExtensions() {
+		kitInstance.SetExtensionContext(extensions.Context{
+			SessionID:   sessionID,
+			CWD:         cwd,
+			Model:       kitInstance.GetModelString(),
+			Interactive: false,
+
+			// Output — route through structured logger.
+			Print:      func(text string) { log.Debug("extension: print", "text", text) },
+			PrintInfo:  func(text string) { log.Info("extension: info", "text", text) },
+			PrintError: func(text string) { log.Error("extension: error", "text", text) },
+			PrintBlock: func(opts extensions.PrintBlockOpts) {
+				log.Info("extension: block", "subtitle", opts.Subtitle, "text", opts.Text)
+			},
+
+			// Message injection — no-ops for now; ACP clients drive prompts.
+			SendMessage:   func(string) {},
+			CancelAndSend: func(string) {},
+			Exit:          func() {},
+
+			// TUI widgets/chrome — silent no-ops (no TUI in ACP).
+			SetWidget:       func(extensions.WidgetConfig) {},
+			RemoveWidget:    func(string) {},
+			SetHeader:       func(extensions.HeaderFooterConfig) {},
+			RemoveHeader:    func() {},
+			SetFooter:       func(extensions.HeaderFooterConfig) {},
+			RemoveFooter:    func() {},
+			SetEditor:       func(extensions.EditorConfig) {},
+			ResetEditor:     func() {},
+			SetEditorText:   func(string) {},
+			SetUIVisibility: func(extensions.UIVisibility) {},
+			SetStatus:       func(string, string, int) {},
+			RemoveStatus:    func(string) {},
+
+			// Interactive prompts — return cancelled (no user to prompt).
+			PromptSelect: func(extensions.PromptSelectConfig) extensions.PromptSelectResult {
+				return extensions.PromptSelectResult{Cancelled: true}
+			},
+			PromptConfirm: func(extensions.PromptConfirmConfig) extensions.PromptConfirmResult {
+				return extensions.PromptConfirmResult{Cancelled: true}
+			},
+			PromptInput: func(extensions.PromptInputConfig) extensions.PromptInputResult {
+				return extensions.PromptInputResult{Cancelled: true}
+			},
+			ShowOverlay: func(extensions.OverlayConfig) extensions.OverlayResult {
+				return extensions.OverlayResult{Cancelled: true, Index: -1}
+			},
+			SuspendTUI: func(callback func()) error { callback(); return nil },
+
+			// Data access — delegate to Kit instance.
+			GetContextStats: func() extensions.ContextStats {
+				s := kitInstance.GetContextStats()
+				return extensions.ContextStats{
+					EstimatedTokens: s.EstimatedTokens,
+					ContextLimit:    s.ContextLimit,
+					UsagePercent:    s.UsagePercent,
+					MessageCount:    s.MessageCount,
+				}
+			},
+			GetMessages:    func() []extensions.SessionMessage { return kitInstance.GetSessionMessages() },
+			GetSessionPath: func() string { return kitInstance.GetSessionFilePath() },
+			AppendEntry: func(entryType, data string) (string, error) {
+				return kitInstance.AppendExtensionEntry(entryType, data)
+			},
+			GetEntries: func(entryType string) []extensions.ExtensionEntry {
+				return kitInstance.GetExtensionEntries(entryType)
+			},
+
+			// Options, model, and tool management.
+			GetOption: func(name string) string { return kitInstance.GetExtensionOption(name) },
+			SetOption: func(name, value string) { kitInstance.SetExtensionOption(name, value) },
+			SetModel: func(modelString string) error {
+				previousModel := kitInstance.GetExtensionContext().Model
+				if err := kitInstance.SetModel(context.Background(), modelString); err != nil {
+					return err
+				}
+				kitInstance.UpdateExtensionContextModel(modelString)
+				kitInstance.EmitModelChange(modelString, previousModel, "extension")
+				return nil
+			},
+			GetAvailableModels: func() []extensions.ModelInfoEntry { return kitInstance.GetAvailableModels() },
+			EmitCustomEvent:    func(name, data string) { kitInstance.EmitExtensionCustomEvent(name, data) },
+			GetAllTools:        func() []extensions.ToolInfo { return kitInstance.GetExtensionToolInfos() },
+			SetActiveTools:     func(names []string) { kitInstance.SetExtensionActiveTools(names) },
+
+			// LLM completions and subagents.
+			Complete: func(req extensions.CompleteRequest) (extensions.CompleteResponse, error) {
+				return kitInstance.ExecuteCompletion(context.Background(), req)
+			},
+			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
+				sdkCfg := kit.SubagentConfig{
+					Prompt:       config.Prompt,
+					Model:        config.Model,
+					SystemPrompt: config.SystemPrompt,
+					Timeout:      config.Timeout,
+					NoSession:    config.NoSession,
+				}
+				if config.OnEvent != nil {
+					sdkCfg.OnEvent = func(e kit.Event) {
+						se := sdkEventToSubagentEvent(e)
+						if se.Type != "" {
+							config.OnEvent(se)
+						}
+					}
+				}
+				result, err := kitInstance.Subagent(context.Background(), sdkCfg)
+				if result == nil {
+					return nil, &extensions.SubagentResult{Error: err}, err
+				}
+				extResult := &extensions.SubagentResult{
+					Response:  result.Response,
+					Error:     result.Error,
+					SessionID: result.SessionID,
+					Elapsed:   result.Elapsed,
+				}
+				if result.Usage != nil {
+					extResult.Usage = &extensions.SubagentUsage{
+						InputTokens:  result.Usage.InputTokens,
+						OutputTokens: result.Usage.OutputTokens,
+					}
+				}
+				return nil, extResult, err
+			},
+
+			// Render — fall back to logging.
+			RenderMessage: func(name, content string) {
+				renderer := kitInstance.GetExtensionMessageRenderer(name)
+				if renderer != nil && renderer.Render != nil {
+					content = renderer.Render(content, 80)
+				}
+				log.Info("extension: message", "renderer", name, "content", content)
+			},
+			ReloadExtensions: func() error { return kitInstance.ReloadExtensions() },
+		})
+		kitInstance.EmitSessionStart()
+	}
+
 	sess := &acpSession{
 		kit:       kitInstance,
 		cwd:       cwd,
@@ -104,3 +255,40 @@ func (s *acpSession) clearCancel() {
 	defer s.cancelMu.Unlock()
 	s.cancelFn = nil
 }
+
+// sdkEventToSubagentEvent converts an SDK event to an extension SubagentEvent.
+func sdkEventToSubagentEvent(e kit.Event) extensions.SubagentEvent {
+	switch ev := e.(type) {
+	case kit.MessageUpdateEvent:
+		return extensions.SubagentEvent{Type: "text", Content: ev.Chunk}
+	case kit.ReasoningDeltaEvent:
+		return extensions.SubagentEvent{Type: "reasoning", Content: ev.Delta}
+	case kit.ToolCallEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_call", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind, ToolArgs: ev.ToolArgs,
+		}
+	case kit.ToolExecutionStartEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_start", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolExecutionEndEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_end", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolResultEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_result", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+			ToolResult: ev.Result, IsError: ev.IsError,
+		}
+	case kit.TurnStartEvent:
+		return extensions.SubagentEvent{Type: "turn_start"}
+	case kit.TurnEndEvent:
+		return extensions.SubagentEvent{Type: "turn_end"}
+	default:
+		return extensions.SubagentEvent{}
+	}
+}
@@ -41,13 +41,15 @@ type AgentConfig struct {
 }

 // ToolCallHandler is a function type for handling tool calls as they happen.
-type ToolCallHandler func(toolName, toolArgs string)
+type ToolCallHandler func(toolCallID, toolName, toolArgs string)

 // ToolExecutionHandler is a function type for handling tool execution start/end events.
-type ToolExecutionHandler func(toolName, toolArgs string, isStarting bool)
+type ToolExecutionHandler func(toolCallID, toolName, toolArgs string, isStarting bool)

 // ToolResultHandler is a function type for handling tool results.
-type ToolResultHandler func(toolName, toolArgs, result string, isError bool)
+// The metadata parameter carries optional structured data (e.g. file diff
+// info) from the tool execution, JSON-encoded. It may be empty.
+type ToolResultHandler func(toolCallID, toolName, toolArgs, result, metadata string, isError bool)

 // ResponseHandler is a function type for handling LLM responses.
 type ResponseHandler func(content string)
@@ -90,6 +92,8 @@ type GenerateWithLoopResult struct {
 	Messages []message.Message
 	// TotalUsage contains aggregate token usage across all steps
 	TotalUsage fantasy.Usage
+	// StopReason is the LLM provider's finish reason for the final response.
+	StopReason string
 }

 // NewAgent creates a new Agent with core tools and optional MCP tool integration.
@@ -283,12 +287,12 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan

 				// Notify about the tool call
 				if onToolCall != nil {
-					onToolCall(tc.ToolName, tc.Input)
+					onToolCall(tc.ToolCallID, tc.ToolName, tc.Input)
 				}

 				// Notify tool execution starting
 				if onToolExecution != nil {
-					onToolExecution(tc.ToolName, tc.Input, true)
+					onToolExecution(tc.ToolCallID, tc.ToolName, tc.Input, true)
 				}

 				return nil
@@ -301,13 +305,13 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				}
 				// Notify tool execution finished
 				if onToolExecution != nil {
-					onToolExecution(tr.ToolName, currentToolArgs, false)
+					onToolExecution(tr.ToolCallID, tr.ToolName, currentToolArgs, false)
 				}

 				if onToolResult != nil {
 					// Extract result text and error status
 					resultText, isError := extractToolResultText(tr)
-					onToolResult(tr.ToolName, currentToolArgs, resultText, isError)
+					onToolResult(tr.ToolCallID, tr.ToolName, currentToolArgs, resultText, tr.ClientMetadata, isError)
 				}

 				return nil
@@ -426,6 +430,7 @@ func convertAgentResult(result *fantasy.AgentResult, originalMessages []fantasy.
 		ConversationMessages: allFantasyMessages,
 		Messages:             allMessages,
 		TotalUsage:           result.TotalUsage,
+		StopReason:           string(result.Response.FinishReason),
 	}
 }

@@ -532,14 +532,14 @@ func (a *App) subscribeSDKEvents(sendFn func(tea.Msg)) func() {
 	unsubs = append(unsubs, k.Subscribe(func(e kit.Event) {
 		switch ev := e.(type) {
 		case kit.ToolCallEvent:
-			sendFn(ToolCallStartedEvent{ToolName: ev.ToolName, ToolArgs: ev.ToolArgs})
+			sendFn(ToolCallStartedEvent{ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, ToolArgs: ev.ToolArgs})
 		case kit.ToolExecutionStartEvent:
-			sendFn(ToolExecutionEvent{ToolName: ev.ToolName, ToolArgs: ev.ToolArgs, IsStarting: true})
+			sendFn(ToolExecutionEvent{ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, ToolArgs: ev.ToolArgs, IsStarting: true})
 		case kit.ToolExecutionEndEvent:
-			sendFn(ToolExecutionEvent{ToolName: ev.ToolName, IsStarting: false})
+			sendFn(ToolExecutionEvent{ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, IsStarting: false})
 		case kit.ToolResultEvent:
 			sendFn(ToolResultEvent{
-				ToolName: ev.ToolName, ToolArgs: ev.ToolArgs,
+				ToolCallID: ev.ToolCallID, ToolName: ev.ToolName, ToolArgs: ev.ToolArgs,
 				Result: ev.Result, IsError: ev.IsError,
 			})
 		case kit.ToolCallContentEvent:
@@ -19,6 +19,8 @@ type ReasoningChunkEvent struct {
 // ToolCallStartedEvent is sent when a tool call has been parsed and is about to execute.
 // It carries the tool name and its arguments for display purposes.
 type ToolCallStartedEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool being called.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments for the tool call.
@@ -28,6 +30,8 @@ type ToolCallStartedEvent struct {
 // ToolExecutionEvent is sent when a tool starts or finishes executing.
 // The IsStarting flag distinguishes between the start and end of execution.
 type ToolExecutionEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool being executed.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments for the tool call (only set when IsStarting is true).
@@ -38,6 +42,8 @@ type ToolExecutionEvent struct {

 // ToolResultEvent is sent after a tool execution completes with its result.
 type ToolResultEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool that was executed.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments that were passed to the tool.
@@ -51,6 +51,7 @@ func TestCredentialManager(t *testing.T) {
 	}
 	if creds == nil {
 		t.Fatal("Expected credentials to be returned")
+		return
 	}
 	if creds.APIKey != testAPIKey {
 		t.Errorf("Expected API key %s, got %s", testAPIKey, creds.APIKey)
@@ -236,6 +237,7 @@ func TestCredentialStorePersistence(t *testing.T) {
 	}
 	if creds == nil {
 		t.Fatal("Expected credentials to persist")
+		return
 	}
 	if creds.APIKey != testAPIKey {
 		t.Errorf("Expected API key %s, got %s", testAPIKey, creds.APIKey)
@@ -76,13 +76,15 @@ func executeEdit(ctx context.Context, call fantasy.ToolCall, workDir string) (fa
 	// If no exact match, try fuzzy matching
 	if count == 0 {
 		if idx, matchLen := fuzzyMatch(normalized, normalizedOld); idx >= 0 {
-			// Apply fuzzy match
+			// Apply fuzzy match — the matched text is the original content slice
+			matchedText := normalized[idx : idx+matchLen]
 			newContent := normalized[:idx] + args.NewText + normalized[idx+matchLen:]
 			if err := os.WriteFile(absPath, []byte(newContent), 0644); err != nil {
 				return fantasy.NewTextErrorResponse(fmt.Sprintf("failed to write file: %v", err)), nil
 			}
 			diff := generateDiff(absPath, normalized, newContent, idx)
-			return fantasy.NewTextResponse(fmt.Sprintf("Applied edit (fuzzy match) to %s\n%s", args.Path, diff)), nil
+			resp := fantasy.NewTextResponse(fmt.Sprintf("Applied edit (fuzzy match) to %s\n%s", args.Path, diff))
+			return fantasy.WithResponseMetadata(resp, editDiffMeta(absPath, matchedText, args.NewText)), nil
 		}
 		return fantasy.NewTextErrorResponse(fmt.Sprintf("old_text not found in %s", args.Path)), nil
 	}
@@ -100,7 +102,23 @@ func executeEdit(ctx context.Context, call fantasy.ToolCall, workDir string) (fa

 	idx := strings.Index(normalized, normalizedOld)
 	diff := generateDiff(absPath, normalized, newContent, idx)
-	return fantasy.NewTextResponse(fmt.Sprintf("Applied edit to %s\n%s", args.Path, diff)), nil
+	resp := fantasy.NewTextResponse(fmt.Sprintf("Applied edit to %s\n%s", args.Path, diff))
+	return fantasy.WithResponseMetadata(resp, editDiffMeta(absPath, normalizedOld, args.NewText)), nil
+}
+
+// editDiffMeta builds the structured metadata attached to edit tool responses.
+func editDiffMeta(path, oldText, newText string) map[string]any {
+	return map[string]any{
+		"file_diffs": []map[string]any{{
+			"path":      path,
+			"additions": strings.Count(newText, "\n") + 1,
+			"deletions": strings.Count(oldText, "\n") + 1,
+			"diff_blocks": []map[string]any{{
+				"old_text": oldText,
+				"new_text": newText,
+			}},
+		}},
+	}
 }

 // fuzzyMatch tries to find old_text with relaxed matching:
@@ -6,12 +6,50 @@ import (
 	"time"

 	"charm.land/fantasy"
-	"github.com/mark3labs/kit/internal/extensions"
 )

 const defaultSubagentTimeout = 5 * time.Minute
 const maxSubagentTimeout = 30 * time.Minute

+// ---------------------------------------------------------------------------
+// Context-based subagent spawner
+// ---------------------------------------------------------------------------
+
+// SubagentSpawnResult carries the outcome of an in-process subagent spawn.
+type SubagentSpawnResult struct {
+	Response     string
+	Error        error
+	SessionID    string
+	InputTokens  int64
+	OutputTokens int64
+	Elapsed      time.Duration
+}
+
+// SubagentSpawnFunc is a callback that spawns an in-process subagent. The
+// parent Kit instance injects this into the context so the core tool can
+// call back without importing pkg/kit (which would create a cycle).
+type SubagentSpawnFunc func(ctx context.Context, prompt, model, systemPrompt string, timeout time.Duration) (*SubagentSpawnResult, error)
+
+type subagentCtxKey struct{}
+
+// WithSubagentSpawner stores a spawn function in the context so that the
+// spawn_subagent core tool can create in-process subagents.
+func WithSubagentSpawner(ctx context.Context, fn SubagentSpawnFunc) context.Context {
+	return context.WithValue(ctx, subagentCtxKey{}, fn)
+}
+
+// getSubagentSpawner retrieves the spawn function from the context.
+func getSubagentSpawner(ctx context.Context) SubagentSpawnFunc {
+	if fn, ok := ctx.Value(subagentCtxKey{}).(SubagentSpawnFunc); ok {
+		return fn
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// spawn_subagent tool
+// ---------------------------------------------------------------------------
+
 type subagentArgs struct {
 	Task           string `json:"task"`
 	Model          string `json:"model,omitempty"`
@@ -24,9 +62,10 @@ func NewSubagentTool(opts ...ToolOption) fantasy.AgentTool {
 	return &coreTool{
 		info: fantasy.ToolInfo{
 			Name: "spawn_subagent",
-			Description: `Spawn a background subagent to perform a task autonomously.
+			Description: `Spawn a subagent to perform a task autonomously.

-The subagent runs as a separate Kit instance with full tool access. Use this to:
+The subagent runs as a separate in-process Kit instance with full tool access
+(except spawning further subagents). Use this to:
 - Delegate independent subtasks that can run in parallel
 - Perform research or analysis without blocking your main work
 - Execute tasks that benefit from a fresh context window
@@ -74,42 +113,53 @@ func executeSubagent(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolRe
 		return fantasy.NewTextErrorResponse("task parameter is required"), nil
 	}

-	// Determine timeout
+	// Determine timeout.
 	timeout := defaultSubagentTimeout
 	if args.TimeoutSeconds > 0 {
 		timeout = min(time.Duration(args.TimeoutSeconds)*time.Second, maxSubagentTimeout)
 	}

-	// Spawn subagent in blocking mode
-	_, result, err := extensions.SpawnSubagent(extensions.SubagentConfig{
-		Prompt:       args.Task,
-		Model:        args.Model,
-		SystemPrompt: args.SystemPrompt,
-		Timeout:      timeout,
-		Blocking:     true,
-	})
-	if err != nil {
-		return fantasy.NewTextErrorResponse(fmt.Sprintf("Failed to spawn subagent: %v", err)), nil
+	// Retrieve in-process spawner from context.
+	spawner := getSubagentSpawner(ctx)
+	if spawner == nil {
+		return fantasy.NewTextErrorResponse(
+			"Error: subagent spawner not available. " +
+				"Ensure Kit is initialized with subagent support.",
+		), fmt.Errorf("no subagent spawner in context")
 	}

-	if result.Error != nil {
-		// Subagent failed but we still have partial output
-		response := fmt.Sprintf("Subagent failed (exit code %d) after %ds.\n\nError: %v",
-			result.ExitCode, int(result.Elapsed.Seconds()), result.Error)
+	// Spawn in-process subagent.
+	result, err := spawner(ctx, args.Task, args.Model, args.SystemPrompt, timeout)
+	if err != nil || result.Error != nil {
+		spawnErr := err
+		if spawnErr == nil {
+			spawnErr = result.Error
+		}
+		response := fmt.Sprintf("Subagent failed after %ds.\n\nError: %v",
+			int(result.Elapsed.Seconds()), spawnErr)
 		if result.Response != "" {
 			response += fmt.Sprintf("\n\nPartial output:\n%s", truncateResponse(result.Response, 8000))
 		}
 		return fantasy.NewTextErrorResponse(response), nil
 	}

-	// Build successful response
+	// Build successful response.
 	response := fmt.Sprintf("Subagent completed successfully in %ds.", int(result.Elapsed.Seconds()))
-	if result.Usage != nil {
-		response += fmt.Sprintf(" (tokens: %d in / %d out)", result.Usage.InputTokens, result.Usage.OutputTokens)
+	if result.InputTokens > 0 || result.OutputTokens > 0 {
+		response += fmt.Sprintf(" (tokens: %d in / %d out)", result.InputTokens, result.OutputTokens)
 	}
 	response += fmt.Sprintf("\n\nResult:\n%s", truncateResponse(result.Response, 12000))

-	return fantasy.NewTextResponse(response), nil
+	resp := fantasy.NewTextResponse(response)
+
+	// Attach subagent session ID as metadata when available.
+	if result.SessionID != "" {
+		resp = fantasy.WithResponseMetadata(resp, map[string]any{
+			"subagent_session_id": result.SessionID,
+		})
+	}
+
+	return resp, nil
 }

 // truncateResponse limits the response length to avoid overwhelming context windows.
@@ -86,8 +86,9 @@ func ReadOnlyTools(opts ...ToolOption) []fantasy.AgentTool {
 	}
 }

-// AllTools returns all available core tools.
-func AllTools(opts ...ToolOption) []fantasy.AgentTool {
+// SubagentTools returns all core tools except spawn_subagent. This prevents
+// infinite recursion when a subagent is itself a Kit instance.
+func SubagentTools(opts ...ToolOption) []fantasy.AgentTool {
 	return []fantasy.AgentTool{
 		NewBashTool(opts...),
 		NewReadTool(opts...),
@@ -96,6 +97,10 @@ func AllTools(opts ...ToolOption) []fantasy.AgentTool {
 		NewGrepTool(opts...),
 		NewFindTool(opts...),
 		NewLsTool(opts...),
-		NewSubagentTool(opts...),
 	}
 }
+
+// AllTools returns all available core tools.
+func AllTools(opts ...ToolOption) []fantasy.AgentTool {
+	return append(SubagentTools(opts...), NewSubagentTool(opts...))
+}
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"

 	"charm.land/fantasy"
 )
@@ -53,6 +54,14 @@ func executeWrite(ctx context.Context, call fantasy.ToolCall, workDir string) (f
 		return fantasy.NewTextErrorResponse(fmt.Sprintf("invalid path: %v", err)), nil
 	}

+	// Read existing content before writing (for diff metadata).
+	var beforeContent string
+	isNew := true
+	if existing, readErr := os.ReadFile(absPath); readErr == nil {
+		beforeContent = string(existing)
+		isNew = false
+	}
+
 	// Create parent directories
 	dir := filepath.Dir(absPath)
 	if err := os.MkdirAll(dir, 0755); err != nil {
@@ -63,5 +72,27 @@ func executeWrite(ctx context.Context, call fantasy.ToolCall, workDir string) (f
 		return fantasy.NewTextErrorResponse(fmt.Sprintf("failed to write file: %v", err)), nil
 	}

-	return fantasy.NewTextResponse(fmt.Sprintf("Wrote %d bytes to %s", len(args.Content), args.Path)), nil
+	resp := fantasy.NewTextResponse(fmt.Sprintf("Wrote %d bytes to %s", len(args.Content), args.Path))
+	return fantasy.WithResponseMetadata(resp, writeDiffMeta(absPath, beforeContent, args.Content, isNew)), nil
+}
+
+// writeDiffMeta builds the structured metadata attached to write tool responses.
+func writeDiffMeta(path, beforeContent, afterContent string, isNew bool) map[string]any {
+	additions := strings.Count(afterContent, "\n") + 1
+	deletions := 0
+	if !isNew {
+		deletions = strings.Count(beforeContent, "\n") + 1
+	}
+	return map[string]any{
+		"file_diffs": []map[string]any{{
+			"path":      path,
+			"additions": additions,
+			"deletions": deletions,
+			"is_new":    isNew,
+			"diff_blocks": []map[string]any{{
+				"old_text": beforeContent,
+				"new_text": afterContent,
+			}},
+		}},
+	}
 }
@@ -1432,7 +1432,9 @@ type EditorConfig struct {
 type ToolCallEvent struct {
 	ToolName   string
 	ToolCallID string
-	Input      string // JSON-encoded tool parameters
+	ToolKind   string         // Tool classification: "execute", "edit", "read", "search", "agent"
+	Input      string         // JSON-encoded tool parameters
+	ParsedArgs map[string]any // Pre-parsed arguments for convenience (nil on parse failure)
 	// Source indicates who initiated the tool call.
 	// Currently always "llm" (all tool calls originate from the LLM agent loop).
 	// Future user-initiated tool features may set this to "user".
@@ -1451,24 +1453,31 @@ func (ToolCallResult) isResult() {}

 // ToolExecutionStartEvent fires when a tool begins executing.
 type ToolExecutionStartEvent struct {
-	ToolName string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
 }

 func (e ToolExecutionStartEvent) Type() EventType { return ToolExecutionStart }

 // ToolExecutionEndEvent fires when a tool finishes executing.
 type ToolExecutionEndEvent struct {
-	ToolName string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
 }

 func (e ToolExecutionEndEvent) Type() EventType { return ToolExecutionEnd }

 // ToolResultEvent fires after tool execution with the output.
 type ToolResultEvent struct {
-	ToolName string
-	Input    string
-	Content  string
-	IsError  bool
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
+	Input      string
+	Content    string
+	IsError    bool
+	Metadata   string // Optional JSON-encoded structured metadata (e.g. file diffs)
 }

 func (e ToolResultEvent) Type() EventType { return ToolResult }
@@ -38,6 +38,11 @@ type SubagentConfig struct {
 	// Called from a goroutine; must be safe for concurrent use.
 	OnOutput func(chunk string)

+	// OnEvent receives real-time events from the subagent's execution:
+	// text chunks, tool calls, tool results, reasoning deltas, etc.
+	// Called synchronously from the subagent's event loop.
+	OnEvent func(SubagentEvent)
+
 	// OnComplete is called when the subagent finishes (success or error).
 	// Called from a goroutine; must be safe for concurrent use.
 	OnComplete func(result SubagentResult)
@@ -47,11 +52,45 @@ type SubagentConfig struct {
 	// and returns immediately with a handle.
 	Blocking bool

+	// NoSession, when true, runs the subagent without persisting a session
+	// file. By default (false), subagent sessions are persisted so they can
+	// be loaded for replay/inspection. Set to true for ephemeral tasks
+	// where session history is not needed.
+	NoSession bool
+
 	// ParentSessionID links the subagent's session to the parent (optional).
-	// When set, the subagent's session is persisted with a parent reference.
+	// When set, the subagent's session header includes a parent reference
+	// so viewers can navigate the session tree.
 	ParentSessionID string
 }

+// SubagentEvent carries a real-time event from a running subagent. Extensions
+// use the Type field to determine what happened and read the relevant fields.
+// This is a concrete struct (not an interface) for Yaegi compatibility.
+type SubagentEvent struct {
+	// Type identifies the event: "text", "reasoning", "tool_call",
+	// "tool_result", "tool_execution_start", "tool_execution_end",
+	// "turn_start", "turn_end".
+	Type string
+
+	// Content carries text for "text" and "reasoning" events.
+	Content string
+
+	// ToolCallID is set on tool_call, tool_result, tool_execution_start,
+	// and tool_execution_end events.
+	ToolCallID string
+	// ToolName is set on tool-related events.
+	ToolName string
+	// ToolKind is set on tool-related events.
+	ToolKind string
+	// ToolArgs is set on tool_call events (JSON-encoded).
+	ToolArgs string
+	// ToolResult is set on tool_result events.
+	ToolResult string
+	// IsError is set on tool_result events.
+	IsError bool
+}
+
 // SubagentResult contains the outcome of a subagent execution.
 type SubagentResult struct {
 	// Response is the subagent's final text response.
@@ -68,6 +107,11 @@ type SubagentResult struct {

 	// Usage contains token usage if available.
 	Usage *SubagentUsage
+
+	// SessionID is the subagent's session identifier, if available.
+	// Populated when the subagent persists its session (requires running
+	// without --no-session). Empty for ephemeral sessions.
+	SessionID string
 }

 // SubagentUsage contains token usage from the subagent's run.
@@ -120,8 +164,10 @@ func (h *SubagentHandle) Done() <-chan struct{} {

 // subagentJSONOutput matches the JSON envelope produced by `kit --json`.
 type subagentJSONOutput struct {
-	Response string `json:"response"`
-	Usage    *struct {
+	Response   string `json:"response"`
+	StopReason string `json:"stop_reason,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	Usage      *struct {
 		InputTokens  int64 `json:"input_tokens"`
 		OutputTokens int64 `json:"output_tokens"`
 	} `json:"usage,omitempty"`
@@ -175,9 +221,11 @@ func SpawnSubagent(cfg SubagentConfig) (*SubagentHandle, *SubagentResult, error)
 	// Build subprocess arguments.
 	args := []string{
 		"--json",
-		"--no-session",
 		"--no-extensions",
 	}
+	if cfg.NoSession {
+		args = append(args, "--no-session")
+	}
 	if cfg.Model != "" {
 		args = append(args, "--model", cfg.Model)
 	}
@@ -294,6 +342,7 @@ func SpawnSubagent(cfg SubagentConfig) (*SubagentHandle, *SubagentResult, error)
 		var parsed subagentJSONOutput
 		if raw != "" && json.Unmarshal([]byte(raw), &parsed) == nil {
 			result.Response = parsed.Response
+			result.SessionID = parsed.SessionID
 			if parsed.Usage != nil {
 				result.Usage = &SubagentUsage{
 					InputTokens:  parsed.Usage.InputTokens,
@@ -115,6 +115,7 @@ func Symbols() interp.Exports {
 			"SubagentResult": reflect.ValueOf((*SubagentResult)(nil)),
 			"SubagentUsage":  reflect.ValueOf((*SubagentUsage)(nil)),
 			"SubagentHandle": reflect.ValueOf((*SubagentHandle)(nil)),
+			"SubagentEvent":  reflect.ValueOf((*SubagentEvent)(nil)),

 			// Event structs
 			"ToolCallEvent":           reflect.ValueOf((*ToolCallEvent)(nil)),
@@ -40,6 +40,37 @@ func ExtensionToolsAsFantasy(defs []ToolDef, runner *Runner) []fantasy.AgentTool
 	return tools
 }

+// coreToolKinds maps built-in tool names to their kind classification.
+var coreToolKinds = map[string]string{
+	"bash":           "execute",
+	"edit":           "edit",
+	"write":          "edit",
+	"read":           "read",
+	"ls":             "read",
+	"grep":           "search",
+	"find":           "search",
+	"spawn_subagent": "agent",
+}
+
+// toolKindFor returns the ToolKind for a given tool name, defaulting to
+// "execute" for unknown tools (including MCP tools).
+func toolKindFor(toolName string) string {
+	if kind, ok := coreToolKinds[toolName]; ok {
+		return kind
+	}
+	return "execute"
+}
+
+// parseToolArgsJSON attempts to parse JSON-encoded tool args into a map.
+// Returns nil on failure (non-fatal convenience parsing).
+func parseToolArgsJSON(input string) map[string]any {
+	var parsed map[string]any
+	if json.Unmarshal([]byte(input), &parsed) == nil {
+		return parsed
+	}
+	return nil
+}
+
 // ---------------------------------------------------------------------------
 // wrappedTool — intercepts tool calls through the extension runner
 // ---------------------------------------------------------------------------
@@ -63,12 +94,16 @@ func (w *wrappedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.T
 			fmt.Errorf("tool %q disabled by extension", toolName)
 	}

+	kind := toolKindFor(toolName)
+
 	// 1. Emit ToolCall — extensions can block execution.
 	if w.runner.HasHandlers(ToolCall) {
 		result, _ := w.runner.Emit(ToolCallEvent{
 			ToolName:   toolName,
 			ToolCallID: call.ID,
+			ToolKind:   kind,
 			Input:      call.Input,
+			ParsedArgs: parseToolArgsJSON(call.Input),
 			Source:     "llm",
 		})
 		if r, ok := result.(ToolCallResult); ok && r.Block {
@@ -83,7 +118,7 @@ func (w *wrappedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.T

 	// 2. Emit ToolExecutionStart.
 	if w.runner.HasHandlers(ToolExecutionStart) {
-		_, _ = w.runner.Emit(ToolExecutionStartEvent{ToolName: toolName})
+		_, _ = w.runner.Emit(ToolExecutionStartEvent{ToolCallID: call.ID, ToolName: toolName, ToolKind: kind})
 	}

 	// 3. Execute the actual tool.
@@ -91,16 +126,19 @@ func (w *wrappedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.T

 	// 4. Emit ToolExecutionEnd.
 	if w.runner.HasHandlers(ToolExecutionEnd) {
-		_, _ = w.runner.Emit(ToolExecutionEndEvent{ToolName: toolName})
+		_, _ = w.runner.Emit(ToolExecutionEndEvent{ToolCallID: call.ID, ToolName: toolName, ToolKind: kind})
 	}

 	// 5. Emit ToolResult — extensions can modify output.
 	if w.runner.HasHandlers(ToolResult) {
 		result, _ := w.runner.Emit(ToolResultEvent{
-			ToolName: toolName,
-			Input:    call.Input,
-			Content:  resp.Content,
-			IsError:  err != nil || resp.IsError,
+			ToolCallID: call.ID,
+			ToolName:   toolName,
+			ToolKind:   kind,
+			Input:      call.Input,
+			Content:    resp.Content,
+			IsError:    err != nil || resp.IsError,
+			Metadata:   resp.Metadata,
 		})
 		if r, ok := result.(ToolResultResult); ok {
 			if r.Content != nil {
@@ -210,10 +210,11 @@ func CreateProvider(ctx context.Context, config *ProviderConfig) (*ProviderResul
 		}
 	}

-	// Validate environment variables
-	if err := registry.ValidateEnvironment(provider, config.ProviderAPIKey); err != nil {
-		return nil, err
-	}
+	// NOTE: We intentionally skip registry.ValidateEnvironment() here.
+	// Each create*Provider function handles its own auth resolution and
+	// produces provider-specific error messages. The early env-var check
+	// was too narrow — it didn't account for stored credentials (e.g.
+	// OAuth tokens from 'kit auth login') and blocked valid auth paths.

 	// Validate config against known model limits when metadata is available
 	if modelInfo != nil {
@@ -1042,9 +1043,21 @@ type oauthTransport struct {
 }

 func (t *oauthTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	// Resolve the freshest available token. The credential manager
+	// automatically refreshes tokens nearing expiry (5-minute buffer).
+	// This keeps long-lived sessions (e.g. ACP) working across token
+	// renewals. Falls back to the originally-provided token if the
+	// credential manager is unavailable.
+	token := t.accessToken
+	if cm, err := auth.NewCredentialManager(); err == nil {
+		if fresh, err := cm.GetValidAccessToken(); err == nil && fresh != "" {
+			token = fresh
+		}
+	}
+
 	newReq := req.Clone(req.Context())
 	newReq.Header.Del("x-api-key")
-	newReq.Header.Set("Authorization", "Bearer "+t.accessToken)
+	newReq.Header.Set("Authorization", "Bearer "+token)
 	newReq.Header.Set("anthropic-beta", "oauth-2025-04-20")
 	newReq.Header.Set("anthropic-version", "2023-06-01")

@@ -78,6 +78,7 @@ func TestCreateOAuthHTTPClient(t *testing.T) {

 			if client == nil {
 				t.Fatal("expected non-nil client")
+				return
 			}

 			// Check that the transport is an oauthTransport
@@ -6,6 +6,8 @@ import (
 	"fmt"
 	"os"
 	"strings"
+
+	"github.com/mark3labs/kit/internal/auth"
 )

 //go:embed embedded_models.json
@@ -171,14 +173,27 @@ func (r *ModelsRegistry) GetRequiredEnvVars(provider string) ([]string, error) {
 	return providerInfo.Env, nil
 }

-// ValidateEnvironment checks if required environment variables are set.
-// Returns nil for providers not in the registry (unknown providers are
-// assumed to handle auth themselves or via --provider-api-key).
+// ValidateEnvironment checks if required credentials are available for a
+// provider. It checks the explicit API key, stored credentials (for
+// providers that support them, such as Anthropic OAuth), and environment
+// variables. Returns nil for providers not in the registry (unknown
+// providers are assumed to handle auth themselves or via --provider-api-key).
 func (r *ModelsRegistry) ValidateEnvironment(provider string, apiKey string) error {
 	if apiKey != "" {
 		return nil
 	}

+	// For anthropic, also check stored credentials (OAuth / API key)
+	// since auth resolution goes through the credential manager, not
+	// just environment variables.
+	if provider == "anthropic" {
+		if cm, err := auth.NewCredentialManager(); err == nil {
+			if has, _ := cm.HasAnthropicCredentials(); has {
+				return nil
+			}
+		}
+	}
+
 	envVars, err := r.GetRequiredEnvVars(provider)
 	if err != nil {
 		// Unknown provider — nothing to validate
@@ -24,6 +24,7 @@ func TestUsageTracker_OAuthCosts(t *testing.T) {
 	stats := regularTracker.GetLastRequestStats()
 	if stats == nil {
 		t.Fatal("Expected stats to be non-nil")
+		return
 	}

 	// Check that costs are calculated for regular API key
@@ -48,6 +49,7 @@ func TestUsageTracker_OAuthCosts(t *testing.T) {
 	oauthStats := oauthTracker.GetLastRequestStats()
 	if oauthStats == nil {
 		t.Fatal("Expected OAuth stats to be non-nil")
+		return
 	}

 	// Check that all costs are $0 for OAuth
@@ -1,6 +1,9 @@
 package kit

-import "sync"
+import (
+	"encoding/json"
+	"sync"
+)

 // ---------------------------------------------------------------------------
 // Event types
@@ -48,6 +51,54 @@ type Event interface {
 	EventType() EventType
 }

+// ---------------------------------------------------------------------------
+// Tool kind constants
+// ---------------------------------------------------------------------------
+
+// ToolKind constants classify what a tool does, enabling UIs to render
+// appropriate visualizations (e.g. diff view for edit tools, command+output
+// for execute tools) and file trackers to identify which results contain
+// modifications.
+const (
+	ToolKindExecute  = "execute" // Shell execution (bash)
+	ToolKindEdit     = "edit"    // File modification (edit, write)
+	ToolKindRead     = "read"    // File reading (read, ls)
+	ToolKindSearch   = "search"  // Content/file search (grep, find)
+	ToolKindSubagent = "agent"   // Subagent spawning (spawn_subagent)
+)
+
+// coreToolKinds maps built-in tool names to their kind. MCP and extension
+// tools without an entry default to ToolKindExecute.
+var coreToolKinds = map[string]string{
+	"bash":           ToolKindExecute,
+	"edit":           ToolKindEdit,
+	"write":          ToolKindEdit,
+	"read":           ToolKindRead,
+	"ls":             ToolKindRead,
+	"grep":           ToolKindSearch,
+	"find":           ToolKindSearch,
+	"spawn_subagent": ToolKindSubagent,
+}
+
+// toolKindFor returns the ToolKind for a given tool name, defaulting to
+// ToolKindExecute for unknown tools.
+func toolKindFor(toolName string) string {
+	if kind, ok := coreToolKinds[toolName]; ok {
+		return kind
+	}
+	return ToolKindExecute
+}
+
+// parseToolArgs attempts to parse a JSON-encoded tool args string into a map.
+// Returns nil on failure (non-fatal convenience parsing).
+func parseToolArgs(toolArgs string) map[string]any {
+	var parsed map[string]any
+	if json.Unmarshal([]byte(toolArgs), &parsed) == nil {
+		return parsed
+	}
+	return nil
+}
+
 // ---------------------------------------------------------------------------
 // Concrete event structs
 // ---------------------------------------------------------------------------
@@ -62,8 +113,9 @@ func (e TurnStartEvent) EventType() EventType { return EventTurnStart }

 // TurnEndEvent fires after the agent finishes processing.
 type TurnEndEvent struct {
-	Response string
-	Error    error
+	Response   string
+	Error      error
+	StopReason string // "end_turn", "max_tokens", "tool_use", "error", etc.
 }

 // EventType implements Event.
@@ -101,8 +153,11 @@ func (e MessageEndEvent) EventType() EventType { return EventMessageEnd }

 // ToolCallEvent fires when a tool call has been parsed.
 type ToolCallEvent struct {
-	ToolName string
-	ToolArgs string
+	ToolCallID string // Stable ID for correlating tool lifecycle events
+	ToolName   string
+	ToolKind   string         // Tool classification: "execute", "edit", "read", "search", "agent"
+	ToolArgs   string         // JSON-encoded arguments
+	ParsedArgs map[string]any // Pre-parsed arguments for convenience (nil on parse failure)
 }

 // EventType implements Event.
@@ -110,8 +165,10 @@ func (e ToolCallEvent) EventType() EventType { return EventToolCall }

 // ToolExecutionStartEvent fires when a tool begins executing.
 type ToolExecutionStartEvent struct {
-	ToolName string
-	ToolArgs string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
+	ToolArgs   string
 }

 // EventType implements Event.
@@ -119,7 +176,9 @@ func (e ToolExecutionStartEvent) EventType() EventType { return EventToolExecuti

 // ToolExecutionEndEvent fires when a tool finishes executing.
 type ToolExecutionEndEvent struct {
-	ToolName string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
 }

 // EventType implements Event.
@@ -127,10 +186,35 @@ func (e ToolExecutionEndEvent) EventType() EventType { return EventToolExecution

 // ToolResultEvent fires after a tool execution completes with its result.
 type ToolResultEvent struct {
-	ToolName string
-	ToolArgs string
-	Result   string
-	IsError  bool
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
+	ToolArgs   string
+	ParsedArgs map[string]any // Pre-parsed arguments for convenience
+	Result     string
+	IsError    bool
+	Metadata   *ToolResultMetadata // Optional structured metadata from tool execution
+}
+
+// ToolResultMetadata carries structured data from tool executions.
+type ToolResultMetadata struct {
+	FileDiffs         []FileDiffInfo `json:"file_diffs,omitempty"`          // Present for edit/write tools
+	SubagentSessionID string         `json:"subagent_session_id,omitempty"` // Present for spawn_subagent tool
+}
+
+// FileDiffInfo describes a file modification from an edit or write tool.
+type FileDiffInfo struct {
+	Path       string      `json:"path"`             // Absolute file path
+	Additions  int         `json:"additions"`        // Lines added
+	Deletions  int         `json:"deletions"`        // Lines removed
+	IsNew      bool        `json:"is_new,omitempty"` // True if file was created (write only)
+	DiffBlocks []DiffBlock `json:"diff_blocks,omitempty"`
+}
+
+// DiffBlock represents a single old→new text replacement within a file.
+type DiffBlock struct {
+	OldText string `json:"old_text"`
+	NewText string `json:"new_text"`
 }

 // EventType implements Event.
@@ -89,11 +89,13 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 	if runner.HasHandlers(extensions.AgentEnd) {
 		m.Subscribe(func(e Event) {
 			if ev, ok := e.(TurnEndEvent); ok {
-				stopReason := "completed"
+				stopReason := ev.StopReason
 				response := ev.Response
 				if ev.Error != nil {
 					stopReason = "error"
 					response = ""
+				} else if stopReason == "" {
+					stopReason = "completed"
 				}
 				_, _ = runner.Emit(extensions.AgentEndEvent{
 					Response:   response,
@@ -31,8 +31,9 @@ const (

 // BeforeToolCallHook is the input for hooks that fire before a tool executes.
 type BeforeToolCallHook struct {
-	ToolName string
-	ToolArgs string
+	ToolCallID string
+	ToolName   string
+	ToolArgs   string
 }

 // BeforeToolCallResult controls whether the tool call proceeds.
@@ -43,10 +44,11 @@ type BeforeToolCallResult struct {

 // AfterToolResultHook is the input for hooks that fire after a tool executes.
 type AfterToolResultHook struct {
-	ToolName string
-	ToolArgs string
-	Result   string
-	IsError  bool
+	ToolCallID string
+	ToolName   string
+	ToolArgs   string
+	Result     string
+	IsError    bool
 }

 // AfterToolResultResult can modify the tool's output before it reaches the LLM.
@@ -258,8 +260,9 @@ func (h *hookedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.To
 	// 1. BeforeToolCall — can block execution.
 	if h.beforeToolCall.hasHooks() {
 		if result := h.beforeToolCall.run(BeforeToolCallHook{
-			ToolName: toolName,
-			ToolArgs: call.Input,
+			ToolCallID: call.ID,
+			ToolName:   toolName,
+			ToolArgs:   call.Input,
 		}); result != nil && result.Block {
 			reason := result.Reason
 			if reason == "" {
@@ -276,10 +279,11 @@ func (h *hookedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.To
 	// 3. AfterToolResult — can modify output.
 	if h.afterToolResult.hasHooks() {
 		if result := h.afterToolResult.run(AfterToolResultHook{
-			ToolName: toolName,
-			ToolArgs: call.Input,
-			Result:   resp.Content,
-			IsError:  err != nil || resp.IsError,
+			ToolCallID: call.ID,
+			ToolName:   toolName,
+			ToolArgs:   call.Input,
+			Result:     resp.Content,
+			IsError:    err != nil || resp.IsError,
 		}); result != nil {
 			if result.Result != nil {
 				resp.Content = *result.Result
@@ -24,6 +24,7 @@ func TestHookRegistry_RegisterAndRun(t *testing.T) {
 	got := hr.run("hello")
 	if got == nil {
 		t.Fatal("expected non-nil result")
+		return
 	}
 	if *got != "handled: hello" {
 		t.Errorf("expected 'handled: hello', got %q", *got)
@@ -51,6 +52,7 @@ func TestHookRegistry_FirstNonNilWins(t *testing.T) {
 	got := hr.run("test")
 	if got == nil {
 		t.Fatal("expected non-nil result")
+		return
 	}
 	if *got != "second: test" {
 		t.Errorf("expected 'second: test', got %q", *got)
@@ -77,6 +79,7 @@ func TestHookRegistry_PriorityOrdering(t *testing.T) {
 	got := hr.run("x")
 	if got == nil {
 		t.Fatal("expected non-nil result")
+		return
 	}
 	if *got != "high" {
 		t.Errorf("expected 'high' (priority 0 runs first), got %q", *got)
@@ -441,6 +444,7 @@ func TestBeforeTurnHook_PromptOverride(t *testing.T) {
 	result := hr.run(BeforeTurnHook{Prompt: "original"})
 	if result == nil {
 		t.Fatal("expected non-nil result")
+		return
 	}
 	if result.Prompt == nil || *result.Prompt != "modified prompt" {
 		t.Errorf("expected prompt override, got %v", result.Prompt)
@@ -462,6 +466,7 @@ func TestBeforeTurnHook_InjectSystemAndContext(t *testing.T) {
 	result := hr.run(BeforeTurnHook{Prompt: "hello"})
 	if result == nil {
 		t.Fatal("expected non-nil result")
+		return
 	}
 	if result.SystemPrompt == nil || *result.SystemPrompt != "be concise" {
 		t.Errorf("expected system prompt injection")
@@ -2,6 +2,7 @@ package kit

 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -13,6 +14,7 @@ import (

 	"github.com/mark3labs/kit/internal/agent"
 	"github.com/mark3labs/kit/internal/config"
+	"github.com/mark3labs/kit/internal/core"
 	"github.com/mark3labs/kit/internal/extensions"
 	"github.com/mark3labs/kit/internal/kitsetup"
 	"github.com/mark3labs/kit/internal/message"
@@ -347,6 +349,50 @@ func (m *Kit) GetSessionMessages() []extensions.SessionMessage {
 	return msgs
 }

+// StructuredMessage represents a conversation message with typed content parts
+// (tool calls, reasoning, finish markers, etc.) instead of flattened text.
+type StructuredMessage struct {
+	ID        string
+	ParentID  string
+	Role      MessageRole
+	Parts     []ContentPart
+	Model     string
+	Provider  string
+	Timestamp string // RFC3339 format
+}
+
+// GetStructuredMessages returns the conversation messages on the current
+// branch with full typed content parts. Unlike GetSessionMessages() which
+// flattens all content to a single text string, this preserves tool calls,
+// tool results, reasoning blocks, and finish markers as distinct typed parts.
+func (m *Kit) GetStructuredMessages() []StructuredMessage {
+	if m.treeSession == nil {
+		return nil
+	}
+	branch := m.treeSession.GetBranch("")
+	var msgs []StructuredMessage
+	for _, entry := range branch {
+		me, ok := entry.(*session.MessageEntry)
+		if !ok {
+			continue
+		}
+		msg, err := me.ToMessage()
+		if err != nil {
+			continue
+		}
+		msgs = append(msgs, StructuredMessage{
+			ID:        me.ID,
+			ParentID:  me.ParentID,
+			Role:      msg.Role,
+			Parts:     msg.Parts,
+			Model:     msg.Model,
+			Provider:  msg.Provider,
+			Timestamp: me.Timestamp.Format("2006-01-02T15:04:05Z07:00"),
+		})
+	}
+	return msgs
+}
+
 // GetSessionFilePath returns the JSONL file path of the current session.
 func (m *Kit) GetSessionFilePath() string {
 	if m.treeSession == nil {
@@ -849,11 +895,19 @@ func InitTreeSession(opts *Options) (*session.TreeManager, error) {
 // New creates a Kit instance using the same initialization as the CLI.
 // It loads configuration, initializes MCP servers, creates the LLM model, and
 // sets up the agent for interaction. Returns an error if initialization fails.
+// viperInitMu serializes viper writes during kit.New(). Viper's global state
+// is not thread-safe, so concurrent calls (e.g. parallel subagent spawns)
+// must not overlap the Set()/Get() window.
+var viperInitMu sync.Mutex
+
 func New(ctx context.Context, opts *Options) (*Kit, error) {
 	if opts == nil {
 		opts = &Options{}
 	}

+	viperInitMu.Lock()
+	defer viperInitMu.Unlock()
+
 	// Set CLI-equivalent defaults for viper. When used as an SDK (without
 	// cobra), these defaults are not registered via flag bindings.
 	setSDKDefaults()
@@ -1150,6 +1204,14 @@ type TurnResult struct {
 	// Response is the assistant's final text response.
 	Response string

+	// StopReason indicates why the turn ended. Derived from the LLM
+	// provider's finish reason: "stop", "length" (max tokens), "tool-calls",
+	// "content-filter", "error", "other", "unknown".
+	StopReason string
+
+	// SessionID is the UUID of the session this turn belongs to.
+	SessionID string
+
 	// TotalUsage is the aggregate token usage across all steps in the turn
 	// (includes tool-calling loop iterations). Nil if the provider didn't
 	// report usage.
@@ -1165,6 +1227,168 @@ type TurnResult struct {
 	Messages []FantasyMessage
 }

+// ---------------------------------------------------------------------------
+// In-process subagent
+// ---------------------------------------------------------------------------
+
+// SubagentConfig configures an in-process subagent spawned via Kit.Subagent().
+type SubagentConfig struct {
+	// Prompt is the task/instruction for the subagent (required).
+	Prompt string
+
+	// Model overrides the parent's model (e.g. "anthropic/claude-haiku-3-5-20241022").
+	// Empty string uses the parent's current model.
+	Model string
+
+	// SystemPrompt provides domain-specific instructions for the subagent.
+	// Empty string uses a minimal default prompt.
+	SystemPrompt string
+
+	// Tools overrides the tool set. If nil, SubagentTools() is used (all
+	// core tools except spawn_subagent, preventing infinite recursion).
+	Tools []Tool
+
+	// NoSession, when true, uses an in-memory ephemeral session. When false
+	// (default), the subagent's session is persisted and can be loaded for
+	// replay/inspection.
+	NoSession bool
+
+	// Timeout limits execution time. Zero means 5 minute default.
+	Timeout time.Duration
+
+	// OnEvent, when set, receives all events from the subagent's event bus.
+	// This enables the parent to stream subagent tool calls, text chunks,
+	// etc. in real time.
+	OnEvent func(Event)
+}
+
+// SubagentResult contains the outcome of an in-process subagent execution.
+type SubagentResult struct {
+	// Response is the subagent's final text response.
+	Response string
+	// Error is set if the subagent failed (nil on success).
+	Error error
+	// SessionID is the subagent's session identifier (for replay).
+	SessionID string
+	// StopReason is the LLM's finish reason for the subagent's final turn.
+	StopReason string
+	// Usage contains token usage from the subagent's run.
+	Usage *FantasyUsage
+	// Elapsed is the total execution time.
+	Elapsed time.Duration
+}
+
+// Subagent spawns an in-process child Kit instance to perform a task. The
+// child gets its own session, event bus, and agent loop but shares the
+// parent's config (API keys, provider settings) and defaults to the parent's
+// model when SubagentConfig.Model is empty.
+//
+// This is the recommended way to run subagents in the SDK — no subprocess,
+// no kit binary dependency, native Go types for results.
+func (m *Kit) Subagent(ctx context.Context, cfg SubagentConfig) (*SubagentResult, error) {
+	if cfg.Prompt == "" {
+		return nil, fmt.Errorf("subagent prompt is required")
+	}
+
+	start := time.Now()
+
+	// Default timeout.
+	timeout := cfg.Timeout
+	if timeout == 0 {
+		timeout = 5 * time.Minute
+	}
+	ctx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	// Resolve model: fall back to parent's model, and inherit the parent's
+	// provider when only a bare model name is given (e.g. "claude-haiku"
+	// instead of "anthropic/claude-haiku"). This avoids provider guessing.
+	model := cfg.Model
+	if model == "" {
+		model = m.modelString
+	} else if !strings.Contains(model, "/") {
+		// Bare model name — prepend parent's provider.
+		if parts := strings.SplitN(m.modelString, "/", 2); len(parts) == 2 {
+			model = parts[0] + "/" + model
+		}
+	}
+
+	// Default system prompt.
+	systemPrompt := cfg.SystemPrompt
+	if systemPrompt == "" {
+		systemPrompt = "You are a helpful coding assistant. Complete the task efficiently and thoroughly."
+	}
+
+	// Default tools: everything except spawn_subagent.
+	tools := cfg.Tools
+	if tools == nil {
+		tools = SubagentTools()
+	}
+
+	// Create child Kit instance. If the requested model fails (bad name,
+	// unsupported provider, etc.), fall back to the parent's model so the
+	// agent gets a useful error message instead of a hard failure.
+	childOpts := &Options{
+		Model:        model,
+		SystemPrompt: systemPrompt,
+		Tools:        tools,
+		NoSession:    cfg.NoSession,
+		Quiet:        true,
+	}
+	child, err := New(ctx, childOpts)
+	if err != nil && model != m.modelString {
+		// Model-specific failure — retry with parent's model.
+		childOpts.Model = m.modelString
+		child, err = New(ctx, childOpts)
+		if err != nil {
+			return &SubagentResult{
+				Error:   fmt.Errorf("failed to create subagent: %w", err),
+				Elapsed: time.Since(start),
+			}, err
+		}
+		// Prepend a note so the agent knows which model is actually running.
+		cfg.Prompt = fmt.Sprintf(
+			"[Note: requested model %q was not available, using %s instead.]\n\n%s",
+			model, m.modelString, cfg.Prompt,
+		)
+	} else if err != nil {
+		return &SubagentResult{
+			Error:   fmt.Errorf("failed to create subagent: %w", err),
+			Elapsed: time.Since(start),
+		}, err
+	}
+	defer func() { _ = child.Close() }()
+
+	// Forward events to parent if requested.
+	if cfg.OnEvent != nil {
+		child.Subscribe(cfg.OnEvent)
+	}
+
+	// Run the prompt.
+	result, err := child.PromptResult(ctx, cfg.Prompt)
+	elapsed := time.Since(start)
+
+	if err != nil {
+		return &SubagentResult{
+			Error:     err,
+			SessionID: child.GetSessionID(),
+			Elapsed:   elapsed,
+		}, err
+	}
+
+	subResult := &SubagentResult{
+		Response:   result.Response,
+		SessionID:  child.GetSessionID(),
+		StopReason: result.StopReason,
+		Elapsed:    elapsed,
+	}
+	if result.TotalUsage != nil {
+		subResult.Usage = result.TotalUsage
+	}
+
+	return subResult, nil
+}
+
 // ---------------------------------------------------------------------------
 // Shared generation helpers
 // ---------------------------------------------------------------------------
@@ -1173,22 +1397,61 @@ type TurnResult struct {
 // All prompt modes (Prompt, Steer, FollowUp, PromptWithOptions) share this
 // single code path so callback wiring is never duplicated.
 func (m *Kit) generate(ctx context.Context, messages []fantasy.Message) (*agent.GenerateWithLoopResult, error) {
+	// Inject the in-process subagent spawner into the context so the
+	// spawn_subagent core tool can create child Kit instances without
+	// importing pkg/kit (which would create an import cycle).
+	ctx = core.WithSubagentSpawner(ctx, func(
+		spawnCtx context.Context, prompt, model, systemPrompt string, timeout time.Duration,
+	) (*core.SubagentSpawnResult, error) {
+		result, err := m.Subagent(spawnCtx, SubagentConfig{
+			Prompt:       prompt,
+			Model:        model,
+			SystemPrompt: systemPrompt,
+			Timeout:      timeout,
+		})
+		if result == nil {
+			return &core.SubagentSpawnResult{Error: err}, err
+		}
+		sr := &core.SubagentSpawnResult{
+			Response:  result.Response,
+			Error:     result.Error,
+			SessionID: result.SessionID,
+			Elapsed:   result.Elapsed,
+		}
+		if result.Usage != nil {
+			sr.InputTokens = result.Usage.InputTokens
+			sr.OutputTokens = result.Usage.OutputTokens
+		}
+		return sr, err
+	})
+
 	return m.agent.GenerateWithLoopAndStreaming(ctx, messages,
-		func(toolName, toolArgs string) {
-			m.events.emit(ToolCallEvent{ToolName: toolName, ToolArgs: toolArgs})
+		func(toolCallID, toolName, toolArgs string) {
+			m.events.emit(ToolCallEvent{
+				ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName),
+				ToolArgs: toolArgs, ParsedArgs: parseToolArgs(toolArgs),
+			})
 		},
-		func(toolName, toolArgs string, isStarting bool) {
+		func(toolCallID, toolName, toolArgs string, isStarting bool) {
 			if isStarting {
-				m.events.emit(ToolExecutionStartEvent{ToolName: toolName, ToolArgs: toolArgs})
+				m.events.emit(ToolExecutionStartEvent{ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName), ToolArgs: toolArgs})
 			} else {
-				m.events.emit(ToolExecutionEndEvent{ToolName: toolName})
+				m.events.emit(ToolExecutionEndEvent{ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName)})
 			}
 		},
-		func(toolName, toolArgs, resultText string, isError bool) {
-			m.events.emit(ToolResultEvent{
-				ToolName: toolName, ToolArgs: toolArgs,
+		func(toolCallID, toolName, toolArgs, resultText, metadata string, isError bool) {
+			evt := ToolResultEvent{
+				ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName),
+				ToolArgs: toolArgs, ParsedArgs: parseToolArgs(toolArgs),
 				Result: resultText, IsError: isError,
-			})
+			}
+			if metadata != "" {
+				var meta ToolResultMetadata
+				if err := json.Unmarshal([]byte(metadata), &meta); err == nil {
+					evt.Metadata = &meta
+				}
+			}
+			m.events.emit(evt)
 		},
 		func(content string) {
 			m.events.emit(ResponseEvent{Content: content})
@@ -1317,8 +1580,10 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr
 		m.lastInputTokensMu.Unlock()
 	}

+	stopReason := result.StopReason
+
 	m.events.emit(MessageEndEvent{Content: responseText})
-	m.events.emit(TurnEndEvent{Response: responseText})
+	m.events.emit(TurnEndEvent{Response: responseText, StopReason: stopReason})

 	// Run AfterTurn hooks.
 	if m.afterTurn.hasHooks() {
@@ -1327,8 +1592,10 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr

 	// Build TurnResult with usage stats.
 	turnResult := &TurnResult{
-		Response: responseText,
-		Messages: result.ConversationMessages,
+		Response:   responseText,
+		StopReason: stopReason,
+		SessionID:  m.GetSessionID(),
+		Messages:   result.ConversationMessages,
 	}
 	totalUsage := result.TotalUsage
 	turnResult.TotalUsage = &totalUsage
@@ -51,3 +51,8 @@ func CodingTools(opts ...ToolOption) []Tool { return core.CodingTools(opts...) }
 // ReadOnlyTools returns tools for read-only exploration:
 // read, grep, find, ls.
 func ReadOnlyTools(opts ...ToolOption) []Tool { return core.ReadOnlyTools(opts...) }
+
+// SubagentTools returns all core tools except spawn_subagent. Use this when
+// creating child Kit instances (in-process subagents) to prevent infinite
+// recursion.
+func SubagentTools(opts ...ToolOption) []Tool { return core.SubagentTools(opts...) }
@@ -5,6 +5,11 @@
      "source": "davis7dotsh/better-context",
      "sourceType": "github",
      "computedHash": "99bc5301f4f839a6f3be99d98955f32f1cd576c218731fa05fa54a003bd20e9b"
+    },
+    "kit-extensions": {
+      "source": "mark3labs/kit",
+      "sourceType": "github",
+      "computedHash": "9347a88bec46dd52727a672b6c8d058955f9f50dfe98708e0c63b85e0779ba96"
    }
  }
 }
@@ -846,8 +846,8 @@ func applyMode(ctx ext.Context, active bool, tools []string) {

 ## Key Files for Reference

- `internal/extensions/api.go` — Complete API type definitions
- `internal/extensions/runner.go` — Event dispatch and state management
- `internal/extensions/loader.go` — Yaegi interpreter setup
- `internal/extensions/symbols.go` — All types exported to extensions
- `examples/extensions/` — 25+ working example extensions
+- [`internal/extensions/api.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/api.go) — Complete API type definitions
+- [`internal/extensions/runner.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/runner.go) — Event dispatch and state management
+- [`internal/extensions/loader.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/loader.go) — Yaegi interpreter setup
+- [`internal/extensions/symbols.go`](https://github.com/mark3labs/kit/blob/main/internal/extensions/symbols.go) — All types exported to extensions
+- [`examples/extensions/`](https://github.com/mark3labs/kit/tree/main/examples/extensions) — 25+ working example extensions
Author	SHA1	Message	Date
Ed Zynda	3167222b72	fix: gracefully recover from bad model names in subagents If the requested model fails (bad name, unsupported provider), fall back to the parent's model instead of returning a hard error. The original prompt is prepended with a note so the agent knows which model is actually running and can adjust future calls.	2026-03-16 13:43:52 +03:00
Ed Zynda	e3b37191b1	fix: inherit parent provider for bare model names in subagents When spawn_subagent is called with a model name like 'claude-haiku' (no provider prefix), prepend the parent's provider instead of letting ParseModelString guess. Only full 'provider/model' strings bypass this.	2026-03-16 13:41:02 +03:00
Ed Zynda	41d5f5e0fb	feat: add OnEvent callback for real-time subagent event streaming Add SubagentEvent type to extension API and OnEvent field to SubagentConfig so extensions can watch subagent tool calls, text chunks, reasoning deltas, and turn lifecycle events in real time. The SDK's Kit.Subagent() already had OnEvent via kit.SubagentConfig. This wires it through to the extension layer with a concrete SubagentEvent struct (Yaegi-safe) and bridges SDK events to it in both cmd/root.go and the ACP server.	2026-03-16 13:06:53 +03:00
Ed Zynda	3ad0b3616d	fix: surface SubagentSessionID in ToolResultMetadata The subagent_session_id was already attached to the fantasy response metadata by internal/core/subagent.go but ToolResultMetadata had no field for it, so json.Unmarshal silently dropped it. Add the field so SDK consumers can detect subagent tools and load their sessions.	2026-03-16 13:01:34 +03:00
Ed Zynda	8831b49b51	feat: in-process subagents replace subprocess spawning Subagents now run as child Kit instances in the same process instead of spawning a kit binary subprocess. This removes the binary dependency, eliminates JSON serialization overhead, and enables SDK-only consumers to use subagents without installing the kit CLI. - Add Kit.Subagent() method for in-process subagent execution - Add SubagentConfig/SubagentResult types to the SDK - Add context-based SubagentSpawnFunc injection so core spawn_subagent tool calls back to Kit.Subagent() without an import cycle - Add SubagentTools() bundle (all core tools minus spawn_subagent) - Add viperInitMu for thread-safe concurrent kit.New() calls - Wire extension ctx.SpawnSubagent and ACP server to use in-process - Child Kit gets parent's model as fallback, in-memory or persisted session, and no extensions (preventing recursive loading)	2026-03-16 11:39:59 +03:00
Ed Zynda	c94edc929b	feat: add rich tool metadata to SDK and extension events (Gaps 1-8) Thread ToolCallID, ToolKind, ParsedArgs, FileDiff metadata, StopReason, SessionID, and StructuredMessages across the SDK event bus, extension wrapper, app bridge, hooks, and ACP server layers. - Gap 1: ToolCallID from Fantasy's ToolCallContent threaded end-to-end - Gap 2: ToolKind via static lookup (execute/edit/read/search/agent) - Gap 3+4: FileDiffInfo with DiffBlocks via fantasy.ToolResponse.Metadata - Gap 5: StopReason from Fantasy FinishReason on TurnEndEvent/TurnResult - Gap 6: Subagent sessions now opt-out (NoSession); SessionID in JSON output - Gap 7: GetStructuredMessages() returns typed ContentParts - Gap 8: ParsedArgs map[string]any on tool events for convenience Edit/write tools attach structured diff metadata. ACP server uses real ToolCallIDs. Extension and SDK events kept in sync with matching fields.	2026-03-16 11:10:05 +03:00
Ed Zynda	e49194a0d4	fix(acp): wire extension context so extensions work in ACP mode Extensions were loaded but non-functional in ACP because SetExtensionContext was never called. Wire a headless context with no-op TUI stubs, functional data/model/tool APIs, and emit SessionStart so extension lifecycle hooks fire during ACP sessions.	2026-03-15 15:29:08 +03:00
Ed Zynda	46b1acf444	fix	2026-03-15 15:10:02 +03:00
Ed Zynda	6a6d201a50	add LSP diagnostics example extension Adds an extension that starts language servers on demand and surfaces diagnostics after file edits, following crush's LSP integration pattern. Hooks into the edit tool lifecycle to diff pre/post diagnostics, display a persistent widget, and expose lsp_diagnostics/lsp_hover tools plus /lsp and /lsp-check slash commands.	2026-03-15 14:29:27 +03:00
Ed Zynda	930cbcb4f2	fix: use full GitHub URLs for file references in kit-extensions skill	2026-03-15 13:01:05 +03:00
Ed Zynda	12e1ef2036	skills	2026-03-15 12:55:47 +03:00
Ed Zynda	a05da5f3ab	fix(auth): support OAuth credentials in ACP mode and auto-refresh tokens Remove the early ValidateEnvironment gate from CreateProvider that only checked env vars and --provider-api-key, blocking stored OAuth credentials from working. Each provider creation function already handles its own auth resolution with clear error messages. Update ValidateEnvironment to also check stored Anthropic credentials so the model selector UI correctly shows Anthropic models for OAuth users. Add automatic token refresh in oauthTransport so long-lived ACP sessions survive token renewals. Surface actionable auth error messages in ACP session creation. Fix pre-existing staticcheck SA5011 warnings in test files.	2026-03-15 12:38:23 +03:00