fix: ensure all message blocks appear below previous content in scrollback

tea.Println inserts above BubbleTea's managed region, but after
StepCompleteEvent the previous response stays in the stream component
(managed region). Any subsequent print (tool results, shell commands,
slash output, errors) would appear above that response — out of order.

Introduce a scrollback buffer: all print helpers now buffer rendered
content via appendScrollback(). At the end of each Update cycle,
drainScrollback() combines everything into a single tea.Println. If
the stream component has unflushed content it is auto-prepended, so
new messages always appear below the previous assistant response.

.agents/skills/kit-extensions/SKILL.md

@@ -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

cmd/acp.go

@@ -1,7 +1,11 @@
 package cmd
 
 import (
+	"bufio"
+	"bytes"
+	"encoding/json"
 	"fmt"
+	"io"
 	"log/slog"
 	"os"
 	"os/signal"
@@ -37,8 +41,10 @@ func runACP(cmd *cobra.Command, _ []string) error {
 	defer agent.Close()
 
 	// Create the stdio connection. The SDK reads JSON-RPC from stdin and
-	// writes responses to stdout.
-	conn := acp.NewAgentSideConnection(agent, os.Stdout, os.Stdin)
+	// writes responses to stdout. We wrap stdin with a normalizer that
+	// fills in optional fields the SDK's generated validation requires
+	// (e.g. mcpServers) so clients that omit them still work.
+	conn := acp.NewAgentSideConnection(agent, os.Stdout, newACPNormalizer(os.Stdin))
 
 	// Wire the connection back to the agent so it can send session updates.
 	agent.SetAgentConnection(conn)
@@ -63,3 +69,91 @@ func runACP(cmd *cobra.Command, _ []string) error {
 
 	return nil
 }
+
+// acpNormalizer wraps an io.Reader carrying newline-delimited JSON-RPC and
+// patches incoming messages so that fields the SDK validates as required —
+// but that some clients (e.g. Zed) omit — are defaulted. This avoids
+// InvalidParams errors without forking the SDK.
+type acpNormalizer struct {
+	scanner *bufio.Scanner
+	buf     bytes.Buffer // leftover bytes from the last normalized line
+}
+
+func newACPNormalizer(r io.Reader) *acpNormalizer {
+	const maxMsg = 10 * 1024 * 1024 // 10 MB, matches SDK buffer
+	s := bufio.NewScanner(r)
+	s.Buffer(make([]byte, 0, 1024*1024), maxMsg)
+	return &acpNormalizer{scanner: s}
+}
+
+// Read satisfies io.Reader. It feeds one normalized JSON line (plus newline)
+// per underlying scan, buffering across short caller reads.
+func (n *acpNormalizer) Read(p []byte) (int, error) {
+	// Drain any leftover bytes from the previous line first.
+	if n.buf.Len() > 0 {
+		return n.buf.Read(p)
+	}
+
+	if !n.scanner.Scan() {
+		if err := n.scanner.Err(); err != nil {
+			return 0, err
+		}
+		return 0, io.EOF
+	}
+
+	line := n.scanner.Bytes()
+	normalized := normalizeACPLine(line)
+	n.buf.Write(normalized)
+	n.buf.WriteByte('\n')
+	return n.buf.Read(p)
+}
+
+// normalizeACPLine ensures session/new and session/load params contain an
+// mcpServers array. Returns the original line unchanged for all other methods.
+func normalizeACPLine(line []byte) []byte {
+	// Quick check: if it already contains mcpServers, nothing to do.
+	if bytes.Contains(line, []byte(`"mcpServers"`)) {
+		return line
+	}
+
+	// Only bother parsing if the method could be session/new or session/load.
+	if !bytes.Contains(line, []byte(`"session/new"`)) &&
+		!bytes.Contains(line, []byte(`"session/load"`)) {
+		return line
+	}
+
+	var msg struct {
+		JSONRPC string          `json:"jsonrpc"`
+		ID      json.RawMessage `json:"id,omitempty"`
+		Method  string          `json:"method"`
+		Params  json.RawMessage `json:"params,omitempty"`
+	}
+	if err := json.Unmarshal(line, &msg); err != nil {
+		return line
+	}
+	if msg.Method != "session/new" && msg.Method != "session/load" {
+		return line
+	}
+
+	// Patch params to include mcpServers: [].
+	var params map[string]json.RawMessage
+	if err := json.Unmarshal(msg.Params, &params); err != nil {
+		return line
+	}
+	if _, ok := params["mcpServers"]; ok {
+		return line
+	}
+	params["mcpServers"] = json.RawMessage(`[]`)
+
+	patched, err := json.Marshal(params)
+	if err != nil {
+		return line
+	}
+	msg.Params = patched
+
+	out, err := json.Marshal(msg)
+	if err != nil {
+		return line
+	}
+	return out
+}

cmd/root.go

@@ -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{}
+	}
+}

internal/acpserver/agent.go

@@ -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

internal/acpserver/session.go

@@ -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{}
+	}
+}

internal/agent/agent.go

@@ -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),
 	}
 }
 

internal/app/app.go

@@ -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:

internal/app/events.go

@@ -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.

internal/auth/credentials_test.go

@@ -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)

internal/core/edit.go

@@ -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:

internal/core/subagent.go

@@ -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.

internal/core/tools.go

@@ -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...))
+}

internal/core/write.go

@@ -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,
+			}},
+		}},
+	}
 }

internal/extensions/api.go

@@ -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 }

internal/extensions/subagent.go

@@ -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,

internal/extensions/symbols.go

@@ -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)),

internal/extensions/wrapper.go

@@ -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 {

internal/models/providers.go

@@ -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")
 

internal/models/providers_test.go

@@ -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

internal/models/registry.go

@@ -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

internal/ui/block_renderer.go

@@ -11,6 +11,7 @@ type blockRenderer struct {
 	align         *lipgloss.Position
 	borderColor   *color.Color
 	background    *color.Color
+	foreground    *color.Color
 	fullWidth     bool
 	noBorder      bool
 	paddingTop    int
@@ -123,6 +124,15 @@ func WithBackground(c color.Color) renderingOption {
 	}
 }
 
+// WithForeground returns a renderingOption that overrides the default text
+// foreground color (theme.Text) for the block. Useful for muted or
+// de-emphasized content blocks.
+func WithForeground(c color.Color) renderingOption {
+	return func(br *blockRenderer) {
+		br.foreground = &c
+	}
+}
+
 // WithWidth returns a renderingOption that sets a specific width for the block
 // in characters. This overrides the default container width and allows precise
 // control over the block's horizontal dimensions.
@@ -167,13 +177,19 @@ func renderContentBlock(content string, containerWidth int, options ...rendering
 
 	theme := GetTheme()
 
+	// Resolve foreground color: caller override or theme default.
+	fgColor := theme.Text
+	if renderer.foreground != nil {
+		fgColor = *renderer.foreground
+	}
+
 	// Single-pass render: padding, border, and foreground in one style.
 	style := lipgloss.NewStyle().
 		PaddingLeft(renderer.paddingLeft).
 		PaddingRight(renderer.paddingRight).
 		PaddingTop(renderer.paddingTop).
 		PaddingBottom(renderer.paddingBottom).
-		Foreground(theme.Text)
+		Foreground(fgColor)
 
 	if hasBorder {
 		style = style.BorderStyle(lipgloss.ThickBorder())

internal/ui/compact_renderer.go

@@ -44,15 +44,20 @@ func (r *CompactRenderer) SetWidth(width int) {
 // and metadata.
 func (r *CompactRenderer) RenderUserMessage(content string, timestamp time.Time) UIMessage {
 	theme := getTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.Secondary).Render(">")
-	label := lipgloss.NewStyle().Foreground(theme.Secondary).Bold(true).Render("User")
+	symbol := lipgloss.NewStyle().Foreground(theme.Info).Render(">")
+	label := lipgloss.NewStyle().Foreground(theme.Info).Bold(true).Render("User")
 
-	// Convert single newlines to paragraph breaks so they survive glamour's
-	// markdown rendering (glamour treats single \n as a soft break).
-	content = strings.ReplaceAll(content, "\n", "\n\n")
-
-	// Format content for user messages (preserve formatting, no truncation)
-	compactContent := r.formatUserAssistantContent(content)
+	// Only run markdown rendering when the message contains code spans or
+	// fenced code blocks. Plain text is rendered directly so that newlines
+	// are preserved without the extra paragraph spacing glamour adds.
+	var compactContent string
+	if strings.Contains(content, "`") {
+		mdContent := strings.ReplaceAll(content, "\n", "\n\n")
+		compactContent = r.formatUserAssistantContent(mdContent)
+		compactContent = removeBlankLines(compactContent)
+	} else {
+		compactContent = content
+	}
 
 	// Handle multi-line content
 	lines := strings.Split(compactContent, "\n")
@@ -170,7 +175,7 @@ func (r *CompactRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 	if extRd != nil && extRd.DisplayName != "" {
 		displayName = extRd.DisplayName
 	}
-	nameStr := lipgloss.NewStyle().Foreground(theme.Tool).Bold(true).Render(displayName)
+	nameStr := lipgloss.NewStyle().Foreground(theme.Info).Bold(true).Render(displayName)
 
 	// Format params — check extension renderer first.
 	paramBudget := max(r.width-10-len(displayName), 20)
@@ -235,8 +240,8 @@ func (r *CompactRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 // formatted to fit on a single line for minimal space usage.
 func (r *CompactRenderer) RenderSystemMessage(content string, timestamp time.Time) UIMessage {
 	theme := getTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.System).Render("*")
-	label := lipgloss.NewStyle().Foreground(theme.System).Bold(true).Render("System")
+	symbol := lipgloss.NewStyle().Foreground(theme.Muted).Render("◇")
+	label := lipgloss.NewStyle().Foreground(theme.Muted).Bold(true).Render("System")
 
 	compactContent := r.formatCompactContent(content)
 

internal/ui/input.go

@@ -89,10 +89,10 @@ func NewInputComponent(width int, title string, appCtrl AppController) *InputCom
 	ta.SetHeight(3)        // Default to 3 lines like huh
 	ta.Focus()
 
-	// Override InsertNewline so only ctrl+j and alt+enter insert newlines.
+	// Override InsertNewline so only ctrl+j and shift+enter insert newlines.
 	// Enter always submits the input.
 	ta.KeyMap.InsertNewline = key.NewBinding(
-		key.WithKeys("ctrl+j", "alt+enter"),
+		key.WithKeys("ctrl+j", "shift+enter"),
 		key.WithHelp("ctrl+j", "insert newline"),
 	)
 
@@ -419,7 +419,7 @@ func (s *InputComponent) View() tea.View {
 			MarginTop(1).
 			PaddingLeft(3)
 
-		hint := "enter submit • ctrl+j / alt+enter new line • ctrl+v paste image"
+		hint := "enter submit • ctrl+j / shift+enter new line • ctrl+v paste image"
 		view.WriteString("\n")
 		view.WriteString(helpStyle.Render(hint))
 	}

internal/ui/messages.go

@@ -3,8 +3,7 @@ package ui
 import (
 	"encoding/json"
 	"fmt"
-	"os"
-	"os/user"
+	"regexp"
 	"sort"
 	"strings"
 	"time"
@@ -12,6 +11,9 @@ import (
 	"charm.land/lipgloss/v2"
 )
 
+// ansiEscapeRe matches ANSI escape sequences used for terminal styling.
+var ansiEscapeRe = regexp.MustCompile(`\x1b\[[0-9;]*m`)
+
 // MessageType represents different categories of messages displayed in the UI,
 // each with distinct visual styling and formatting rules.
 type MessageType int
@@ -154,21 +156,6 @@ type MessageRenderer struct {
 	getToolRenderer func(toolName string) *ToolRendererData
 }
 
-// getSystemUsername returns the current system username, fallback to "User"
-func getSystemUsername() string {
-	if currentUser, err := user.Current(); err == nil && currentUser.Username != "" {
-		return currentUser.Username
-	}
-	// Fallback to environment variable
-	if username := os.Getenv("USER"); username != "" {
-		return username
-	}
-	if username := os.Getenv("USERNAME"); username != "" {
-		return username
-	}
-	return "User"
-}
-
 // NewMessageRenderer creates and initializes a new MessageRenderer with the specified
 // terminal width and debug mode setting. The width parameter determines line wrapping
 // and layout calculations.
@@ -189,31 +176,30 @@ func (r *MessageRenderer) SetWidth(width int) {
 // formatting, including the system username, timestamp, and markdown-rendered content.
 // The message is displayed with a colored right border for visual distinction.
 func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time) UIMessage {
-	// Format timestamp and username
-	timeStr := timestamp.Local().Format("15:04")
-	username := getSystemUsername()
-
-	// Convert single newlines to paragraph breaks so they survive glamour's
-	// markdown rendering (glamour treats single \n as a soft break).
-	content = strings.ReplaceAll(content, "\n", "\n\n")
-
 	theme := getTheme()
 
-	messageContent := r.renderMarkdown(content, r.width-8) // Account for padding and borders
+	// Only run markdown rendering when the message contains code spans or
+	// fenced code blocks. Plain text is rendered directly so that newlines
+	// are preserved without the extra paragraph spacing glamour adds.
+	var messageContent string
+	if strings.Contains(content, "`") {
+		// Glamour treats single \n as a soft break, so convert to paragraph
+		// breaks and collapse the resulting blank lines after rendering.
+		mdContent := strings.ReplaceAll(content, "\n", "\n\n")
+		messageContent = r.renderMarkdown(mdContent, r.width-8)
+		messageContent = removeBlankLines(messageContent)
+	} else {
+		messageContent = content
+	}
 
-	// Create info line
-	info := fmt.Sprintf(" %s (%s)", username, timeStr)
+	fullContent := strings.TrimSuffix(messageContent, "\n")
 
-	// Combine content and info
-	fullContent := strings.TrimSuffix(messageContent, "\n") + "\n" +
-		lipgloss.NewStyle().Foreground(theme.VeryMuted).Render(info)
-
-	// Use the block renderer — left border with Primary color, no background.
+	// Left border with Blue color for user messages.
 	rendered := renderContentBlock(
 		fullContent,
 		r.width,
 		WithAlign(lipgloss.Left),
-		WithBorderColor(theme.Primary),
+		WithBorderColor(theme.Info),
 		WithMarginBottom(1),
 	)
 
@@ -230,14 +216,8 @@ func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time)
 // are displayed with a special "Finished without output" message. The message features
 // a colored left border for visual distinction.
 func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage {
-	// Format timestamp and model info with better defaults
-	timeStr := timestamp.Local().Format("15:04")
-	if modelName == "" {
-		modelName = "Assistant"
-	}
-
-	// Handle empty content with better styling
 	theme := getTheme()
+
 	var messageContent string
 	if strings.TrimSpace(content) == "" {
 		messageContent = lipgloss.NewStyle().
@@ -246,21 +226,16 @@ func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.
 			Align(lipgloss.Center).
 			Render("Finished without output")
 	} else {
-		messageContent = r.renderMarkdown(content, r.width-8) // Account for padding and borders
+		messageContent = r.renderMarkdown(content, r.width-8)
 	}
 
-	// Create info line
-	info := fmt.Sprintf(" %s (%s)", modelName, timeStr)
+	fullContent := strings.TrimSuffix(messageContent, "\n")
 
-	// Combine content and info
-	fullContent := strings.TrimSuffix(messageContent, "\n") + "\n" +
-		lipgloss.NewStyle().Foreground(theme.VeryMuted).Render(info)
-
-	// Use the new block renderer — no borders for agent messages.
+	// Left border with Primary (Mauve) color for assistant messages.
 	rendered := renderContentBlock(
 		fullContent,
 		r.width,
-		WithNoBorder(),
+		WithBorderColor(theme.Primary),
 		WithMarginBottom(1),
 	)
 
@@ -276,35 +251,24 @@ func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.
 // and informational notifications. These messages are displayed with a distinctive system
 // color border and "KIT System" label to differentiate them from user and AI content.
 func (r *MessageRenderer) RenderSystemMessage(content string, timestamp time.Time) UIMessage {
-	// Format timestamp
-	timeStr := timestamp.Local().Format("15:04")
-
-	// Handle empty content with better styling
 	theme := getTheme()
+
 	var messageContent string
 	if strings.TrimSpace(content) == "" {
-		messageContent = lipgloss.NewStyle().
-			Italic(true).
-			Foreground(theme.Muted).
-			Align(lipgloss.Center).
-			Render("No content available")
+		messageContent = "No content available"
+	} else if strings.Contains(content, "`") {
+		messageContent = r.renderMarkdown(content, r.width-8)
 	} else {
-		messageContent = r.renderMarkdown(content, r.width-8) // Account for padding and borders
+		messageContent = content
 	}
 
-	// Create info line
-	info := fmt.Sprintf(" KIT System (%s)", timeStr)
+	fullContent := "◇ " + strings.TrimSuffix(messageContent, "\n")
 
-	// Combine content and info
-	fullContent := strings.TrimSuffix(messageContent, "\n") + "\n" +
-		lipgloss.NewStyle().Foreground(theme.VeryMuted).Render(info)
-
-	// Use the new block renderer
 	rendered := renderContentBlock(
 		fullContent,
 		r.width,
-		WithAlign(lipgloss.Left),
-		WithBorderColor(theme.System),
+		WithNoBorder(),
+		WithForeground(theme.Muted),
 		WithMarginBottom(1),
 	)
 
@@ -322,29 +286,22 @@ func (r *MessageRenderer) RenderSystemMessage(content string, timestamp time.Tim
 func (r *MessageRenderer) RenderDebugMessage(message string, timestamp time.Time) UIMessage {
 	baseStyle := lipgloss.NewStyle()
 
-	// Create the main message style with border using tool color
 	theme := getTheme()
 	style := baseStyle.
-		Width(r.width - 3). // Account for left margin
+		Width(r.width - 3).
 		BorderLeft(true).
 		Foreground(theme.Muted).
 		BorderForeground(theme.Tool).
 		BorderStyle(lipgloss.ThickBorder()).
 		PaddingLeft(1).
-		MarginLeft(2).  // Add left margin like other messages
-		MarginBottom(1) // Add bottom margin
+		MarginLeft(2).
+		MarginBottom(1)
 
-	// Format timestamp
-	timeStr := timestamp.Local().Format("02 Jan 2006 03:04 PM")
-
-	// Create header with debug icon
 	header := baseStyle.
 		Foreground(theme.Tool).
 		Bold(true).
 		Render("🔍 Debug Output")
 
-	// Process and format the message content
-	// Split into lines and format each one
 	lines := strings.Split(message, "\n")
 	var formattedLines []string
 	for _, line := range lines {
@@ -357,17 +314,9 @@ func (r *MessageRenderer) RenderDebugMessage(message string, timestamp time.Time
 		Foreground(theme.Muted).
 		Render(strings.Join(formattedLines, "\n"))
 
-	// Create info line
-	info := baseStyle.
-		Width(r.width - 5). // Account for margins and padding
-		Foreground(theme.Muted).
-		Render(fmt.Sprintf(" KIT (%s)", timeStr))
-
-	// Combine all parts
 	fullContent := lipgloss.JoinVertical(lipgloss.Left,
 		header,
 		content,
-		info,
 	)
 
 	return UIMessage{
@@ -382,7 +331,6 @@ func (r *MessageRenderer) RenderDebugMessage(message string, timestamp time.Time
 func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timestamp time.Time) UIMessage {
 	baseStyle := lipgloss.NewStyle()
 
-	// Create the main message style with border using tool color
 	theme := getTheme()
 	style := baseStyle.
 		Width(r.width - 1).
@@ -392,16 +340,11 @@ func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timest
 		BorderStyle(lipgloss.ThickBorder()).
 		PaddingLeft(1)
 
-	// Format timestamp
-	timeStr := timestamp.Local().Format("02 Jan 2006 03:04 PM")
-
-	// Create header with debug icon
 	header := baseStyle.
 		Foreground(theme.Tool).
 		Bold(true).
 		Render("🔧 Debug Configuration")
 
-	// Format configuration settings
 	var configLines []string
 	for key, value := range config {
 		if value != nil {
@@ -413,18 +356,10 @@ func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timest
 		Foreground(theme.Muted).
 		Render(strings.Join(configLines, "\n"))
 
-	// Create info line
-	info := baseStyle.
-		Width(r.width - 1).
-		Foreground(theme.Muted).
-		Render(fmt.Sprintf(" KIT (%s)", timeStr))
-
-	// Combine parts
 	parts := []string{header}
 	if len(configLines) > 0 {
 		parts = append(parts, configContent)
 	}
-	parts = append(parts, info)
 
 	rendered := style.Render(
 		lipgloss.JoinVertical(lipgloss.Left, parts...),
@@ -442,26 +377,15 @@ func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timest
 // bold text to ensure visibility. Error messages include timestamp information and
 // are displayed with an error-colored border for immediate recognition.
 func (r *MessageRenderer) RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage {
-	// Format timestamp
-	timeStr := timestamp.Local().Format("15:04")
-
-	// Format error content
 	theme := getTheme()
+
 	errorContent := lipgloss.NewStyle().
 		Foreground(theme.Error).
 		Bold(true).
 		Render(errorMsg)
 
-	// Create info line
-	info := fmt.Sprintf(" Error (%s)", timeStr)
-
-	// Combine content and info
-	fullContent := errorContent + "\n" +
-		lipgloss.NewStyle().Foreground(theme.VeryMuted).Render(info)
-
-	// Use the new block renderer
 	rendered := renderContentBlock(
-		fullContent,
+		errorContent,
 		r.width,
 		WithAlign(lipgloss.Left),
 		WithBorderColor(theme.Error),
@@ -559,7 +483,7 @@ func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 	if extRd != nil && extRd.DisplayName != "" {
 		displayName = extRd.DisplayName
 	}
-	nameStr := lipgloss.NewStyle().Foreground(theme.Tool).Bold(true).Render(displayName)
+	nameStr := lipgloss.NewStyle().Foreground(theme.Info).Bold(true).Render(displayName)
 
 	// Format params with width budget for the header line.
 	// Check extension renderer for custom header params first.
@@ -710,3 +634,19 @@ func (r *MessageRenderer) renderMarkdown(content string, width int) string {
 	rendered := toMarkdown(content, width)
 	return strings.TrimSuffix(rendered, "\n")
 }
+
+// removeBlankLines removes lines that are visually blank from rendered output.
+// Glamour wraps every character (including padding spaces) with ANSI color
+// codes, so we must strip escape sequences before checking whether a line is
+// empty. This collapses paragraph spacing so user messages render without
+// extra vertical gaps.
+func removeBlankLines(s string) string {
+	lines := strings.Split(s, "\n")
+	filtered := lines[:0]
+	for _, line := range lines {
+		if strings.TrimSpace(ansiEscapeRe.ReplaceAllString(line, "")) != "" {
+			filtered = append(filtered, line)
+		}
+	}
+	return strings.Join(filtered, "\n")
+}

internal/ui/model.go

@@ -396,6 +396,20 @@ type AppModel struct {
 	// the input and move to scrollback when the agent picks them up.
 	queuedMessages []string
 
+	// pendingUserPrints holds user messages that have been consumed from the
+	// queue but not yet printed to scrollback. They are deferred until
+	// SpinnerEvent{Show: true} so the previous assistant response can be
+	// flushed first, preserving chronological order.
+	pendingUserPrints []string
+
+	// scrollbackBuf collects rendered content during a single Update() call.
+	// All print helpers append here instead of returning tea.Println directly.
+	// The buffer is drained into a single atomic tea.Println at the end of
+	// each Update call via drainScrollback(). If the stream component has
+	// unflushed content, it is automatically prepended so that new messages
+	// always appear below the previous assistant response.
+	scrollbackBuf []string
+
 	// canceling tracks whether the user has pressed ESC once during stateWorking.
 	// A second ESC within 2 seconds will cancel the current step.
 	canceling bool
@@ -829,7 +843,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if m.setModel != nil {
 			previousModel := m.providerName + "/" + m.modelName
 			if err := m.setModel(msg.ModelString); err != nil {
-				cmds = append(cmds, m.printSystemMessage(fmt.Sprintf("Failed to switch model: %v", err)))
+				m.printSystemMessage(fmt.Sprintf("Failed to switch model: %v", err))
 			} else {
 				// Update display state directly — we cannot use
 				// NotifyModelChanged (prog.Send) from inside Update()
@@ -839,7 +853,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 					m.providerName = parts[0]
 					m.modelName = parts[1]
 				}
-				cmds = append(cmds, m.printSystemMessage(fmt.Sprintf("Switched to %s", msg.ModelString)))
+				m.printSystemMessage(fmt.Sprintf("Switched to %s", msg.ModelString))
 				if m.emitModelChange != nil {
 					emit := m.emitModelChange
 					newModel := msg.ModelString
@@ -848,6 +862,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				}
 			}
 		}
+		cmds = append(cmds, m.drainScrollback())
 		return m, tea.Batch(cmds...)
 
 	case ModelSelectorCancelledMsg:
@@ -1018,6 +1033,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			if cmd := m.handleSlashCommand(sc); cmd != nil {
 				cmds = append(cmds, cmd)
 			}
+			cmds = append(cmds, m.drainScrollback())
 			return m, tea.Batch(cmds...)
 		}
 
@@ -1031,16 +1047,19 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 					if cmd := m.handleCompactCommand(strings.TrimSpace(args)); cmd != nil {
 						cmds = append(cmds, cmd)
 					}
+					cmds = append(cmds, m.drainScrollback())
 					return m, tea.Batch(cmds...)
 				case "/model":
 					if cmd := m.handleModelCommand(strings.TrimSpace(args)); cmd != nil {
 						cmds = append(cmds, cmd)
 					}
+					cmds = append(cmds, m.drainScrollback())
 					return m, tea.Batch(cmds...)
 				case "/thinking":
 					if cmd := m.handleThinkingCommand(strings.TrimSpace(args)); cmd != nil {
 						cmds = append(cmds, cmd)
 					}
+					cmds = append(cmds, m.drainScrollback())
 					return m, tea.Batch(cmds...)
 				}
 			}
@@ -1091,15 +1110,19 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			if qLen > 0 {
 				// Queued: anchor the message text above the input with a
 				// "queued" badge. It will be printed to scrollback when
-				// the agent picks it up (on QueueUpdatedEvent).
+				// the agent picks it up (via SpinnerEvent).
 				m.queuedMessages = append(m.queuedMessages, displayText)
 				m.distributeHeight()
 			} else {
-				// Started immediately: print to scrollback now.
-				cmds = append(cmds, m.printUserMessage(displayText))
+				// Started immediately. Flush any leftover stream content
+				// from the previous step first, then print the user
+				// message — combined via the scrollback buffer so
+				// scrollback stays in chronological order.
+				m.pendingUserPrints = append(m.pendingUserPrints, displayText)
+				m.flushStreamAndPendingUserMessages()
 			}
 		} else {
-			cmds = append(cmds, m.printUserMessage(displayText))
+			m.printUserMessage(displayText)
 		}
 		if m.state != stateWorking {
 			m.state = stateWorking
@@ -1119,10 +1142,11 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// SpinnerEvent{Show: true} means a new agent step has started (either
 		// freshly or from the queue after a previous step completed). Flush
 		// any leftover stream content from the previous step to scrollback
-		// before starting the new one. This deferred flush avoids shrinking
-		// the view at step-completion time (which leaves blank lines).
+		// before starting the new one, followed by any pending user messages
+		// from the queue. Everything goes through the scrollback buffer to
+		// guarantee chronological ordering.
 		if msg.Show {
-			cmds = append(cmds, m.flushStreamContent())
+			m.flushStreamAndPendingUserMessages()
 			m.state = stateWorking
 			m.distributeHeight()
 		}
@@ -1148,7 +1172,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// always completes before tool calls fire). The tool call itself is
 		// NOT printed here — a unified block (header + result) will be
 		// rendered when the ToolResultEvent arrives.
-		cmds = append(cmds, m.flushStreamContent())
+		m.flushStreamContent()
 
 	case app.ToolExecutionEvent:
 		// Pass to stream component for execution spinner display.
@@ -1158,8 +1182,8 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 
 	case app.ToolResultEvent:
-		// Print tool result immediately to scrollback.
-		cmds = append(cmds, m.printToolResult(msg))
+		// Buffer tool result for scrollback.
+		m.printToolResult(msg)
 		// Start spinner again while waiting for the next LLM response.
 		if m.stream != nil {
 			_, cmd := m.stream.Update(app.SpinnerEvent{Show: true})
@@ -1179,7 +1203,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// In non-streaming mode (no stream content accumulated), print the text.
 		hasStreamContent := m.stream != nil && m.stream.GetRenderedContent() != ""
 		if !hasStreamContent && msg.Content != "" {
-			cmds = append(cmds, m.printAssistantMessage(msg.Content))
+			m.printAssistantMessage(msg.Content)
 			if m.stream != nil {
 				m.stream.Reset()
 			}
@@ -1189,13 +1213,14 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// Informational — no action needed by parent.
 
 	case app.QueueUpdatedEvent:
-		// drainQueue popped item(s) from the queue. Move consumed messages
-		// from the anchored display to scrollback (they are now being processed
-		// or about to be).
+		// drainQueue popped item(s) from the queue. Move consumed
+		// messages to pendingUserPrints — they will be printed to
+		// scrollback in the next SpinnerEvent{Show: true} after the
+		// previous assistant response is flushed.
 		for len(m.queuedMessages) > msg.Length {
 			text := m.queuedMessages[0]
 			m.queuedMessages = m.queuedMessages[1:]
-			cmds = append(cmds, m.printUserMessage(text))
+			m.pendingUserPrints = append(m.pendingUserPrints, text)
 		}
 		m.distributeHeight()
 
@@ -1232,7 +1257,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			cmds = append(cmds, cmd)
 		}
 		if msg.Err != nil {
-			cmds = append(cmds, m.printErrorResponse(msg))
+			m.printErrorResponse(msg)
 		}
 		m.state = stateInput
 		m.canceling = false
@@ -1242,14 +1267,14 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			m.stream.Reset()
 		}
 		m.state = stateInput
-		cmds = append(cmds, m.printCompactResult(msg))
+		m.printCompactResult(msg)
 
 	case app.CompactErrorEvent:
 		if m.stream != nil {
 			m.stream.Reset()
 		}
 		m.state = stateInput
-		cmds = append(cmds, m.printSystemMessage(fmt.Sprintf("Compaction failed: %v", msg.Err)))
+		m.printSystemMessage(fmt.Sprintf("Compaction failed: %v", msg.Err))
 
 	case app.ModelChangedEvent:
 		// Extension changed the model — update display name in status bar
@@ -1357,17 +1382,16 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case extensionCmdResultMsg:
 		// Async extension slash command completed. Render output/error.
 		if msg.err != nil {
-			cmds = append(cmds, m.printSystemMessage(
-				fmt.Sprintf("Command %s error: %v", msg.name, msg.err)))
+			m.printSystemMessage(fmt.Sprintf("Command %s error: %v", msg.name, msg.err))
 		} else if msg.output != "" {
-			cmds = append(cmds, m.printSystemMessage(msg.output))
+			m.printSystemMessage(msg.output)
 		}
 
 	case beforeSessionSwitchResultMsg:
 		// Async before-session-switch hook completed. Proceed with the
 		// session reset if the hook did not cancel.
 		if msg.cancelled {
-			cmds = append(cmds, m.printSystemMessage(msg.reason))
+			m.printSystemMessage(msg.reason)
 		} else {
 			cmds = append(cmds, m.performNewSession())
 		}
@@ -1376,7 +1400,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// Async before-fork hook completed. Proceed with the fork if the
 		// hook did not cancel.
 		if msg.cancelled {
-			cmds = append(cmds, m.printSystemMessage(msg.reason))
+			m.printSystemMessage(msg.reason)
 		} else {
 			cmds = append(cmds, m.performFork(msg.targetID, msg.isUser, msg.userText))
 		}
@@ -1385,15 +1409,15 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// Extension output — route through styled renderers when a level is set.
 		switch msg.Level {
 		case "info":
-			cmds = append(cmds, m.printSystemMessage(msg.Text))
+			m.printSystemMessage(msg.Text)
 		case "error":
-			cmds = append(cmds, m.printErrorResponse(app.StepErrorEvent{
+			m.printErrorResponse(app.StepErrorEvent{
 				Err: fmt.Errorf("%s", msg.Text),
-			}))
+			})
 		case "block":
-			cmds = append(cmds, m.printExtensionBlock(msg))
+			m.printExtensionBlock(msg)
 		default:
-			cmds = append(cmds, tea.Println(msg.Text))
+			m.appendScrollback(msg.Text)
 		}
 
 	default:
@@ -1408,6 +1432,7 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 	}
 
+	cmds = append(cmds, m.drainScrollback())
 	return m, tea.Batch(cmds...)
 }
 
@@ -1753,30 +1778,28 @@ func (m *AppModel) renderQueuedMessages() string {
 // Print helpers — emit content to scrollback via tea.Println
 // --------------------------------------------------------------------------
 
-// printUserMessage renders a user message and emits it above the BT region.
-func (m *AppModel) printUserMessage(text string) tea.Cmd {
-	return tea.Println(m.renderer.RenderUserMessage(text, time.Now()).Content)
+// printUserMessage renders a user message into the scrollback buffer.
+func (m *AppModel) printUserMessage(text string) {
+	m.appendScrollback(m.renderer.RenderUserMessage(text, time.Now()).Content)
 }
 
-// printAssistantMessage renders an assistant message and emits it above the BT region.
-func (m *AppModel) printAssistantMessage(text string) tea.Cmd {
-	if text == "" {
-		return nil
+// printAssistantMessage renders an assistant message into the scrollback buffer.
+func (m *AppModel) printAssistantMessage(text string) {
+	if text != "" {
+		m.appendScrollback(m.renderer.RenderAssistantMessage(text, time.Now(), m.modelName).Content)
 	}
-	return tea.Println(m.renderer.RenderAssistantMessage(text, time.Now(), m.modelName).Content)
 }
 
-// printToolResult renders a tool result message and emits it above the BT region.
-func (m *AppModel) printToolResult(evt app.ToolResultEvent) tea.Cmd {
-	return tea.Println(m.renderer.RenderToolMessage(evt.ToolName, evt.ToolArgs, evt.Result, evt.IsError).Content)
+// printToolResult renders a tool result message into the scrollback buffer.
+func (m *AppModel) printToolResult(evt app.ToolResultEvent) {
+	m.appendScrollback(m.renderer.RenderToolMessage(evt.ToolName, evt.ToolArgs, evt.Result, evt.IsError).Content)
 }
 
-// printErrorResponse renders an error message and emits it above the BT region.
-func (m *AppModel) printErrorResponse(evt app.StepErrorEvent) tea.Cmd {
-	if evt.Err == nil {
-		return nil
+// printErrorResponse renders an error message into the scrollback buffer.
+func (m *AppModel) printErrorResponse(evt app.StepErrorEvent) {
+	if evt.Err != nil {
+		m.appendScrollback(m.renderer.RenderErrorMessage(evt.Err.Error(), time.Now()).Content)
 	}
-	return tea.Println(m.renderer.RenderErrorMessage(evt.Err.Error(), time.Now()).Content)
 }
 
 // --------------------------------------------------------------------------
@@ -1791,15 +1814,15 @@ func (m *AppModel) handleSlashCommand(sc *SlashCommand) tea.Cmd {
 	case "/quit":
 		return tea.Quit
 	case "/help":
-		return m.printHelpMessage()
+		m.printHelpMessage()
 	case "/tools":
-		return m.printToolsMessage()
+		m.printToolsMessage()
 	case "/servers":
-		return m.printServersMessage()
+		m.printServersMessage()
 	case "/usage":
-		return m.printUsageMessage()
+		m.printUsageMessage()
 	case "/reset-usage":
-		return m.printResetUsage()
+		m.printResetUsage()
 	case "/model":
 		return m.handleModelCommand("")
 	case "/thinking":
@@ -1810,14 +1833,13 @@ func (m *AppModel) handleSlashCommand(sc *SlashCommand) tea.Cmd {
 		if m.appCtrl != nil {
 			m.appCtrl.ClearMessages()
 		}
-		return m.printSystemMessage("Conversation cleared. Starting fresh.")
+		m.printSystemMessage("Conversation cleared. Starting fresh.")
 	case "/clear-queue":
 		if m.appCtrl != nil {
 			m.appCtrl.ClearQueue()
 		}
 		m.queuedMessages = m.queuedMessages[:0]
 		m.distributeHeight()
-		return nil
 
 	case "/tree":
 		return m.handleTreeCommand()
@@ -1831,18 +1853,19 @@ func (m *AppModel) handleSlashCommand(sc *SlashCommand) tea.Cmd {
 		return m.handleSessionInfoCommand()
 
 	default:
-		return m.printSystemMessage(fmt.Sprintf("Unknown command: %s", sc.Name))
+		m.printSystemMessage(fmt.Sprintf("Unknown command: %s", sc.Name))
 	}
+	return nil
 }
 
-// printSystemMessage renders a system-level message and emits it above the BT region.
-func (m *AppModel) printSystemMessage(text string) tea.Cmd {
-	return tea.Println(m.renderer.RenderSystemMessage(text, time.Now()).Content)
+// printSystemMessage renders a system-level message into the scrollback buffer.
+func (m *AppModel) printSystemMessage(text string) {
+	m.appendScrollback(m.renderer.RenderSystemMessage(text, time.Now()).Content)
 }
 
 // printExtensionBlock renders a custom styled block from an extension with
-// caller-chosen border color and optional subtitle, then emits it to scrollback.
-func (m *AppModel) printExtensionBlock(evt app.ExtensionPrintEvent) tea.Cmd {
+// caller-chosen border color and optional subtitle into the scrollback buffer.
+func (m *AppModel) printExtensionBlock(evt app.ExtensionPrintEvent) {
 	theme := GetTheme()
 
 	// Resolve border color: use the extension's hex value, fall back to theme accent.
@@ -1865,7 +1888,7 @@ func (m *AppModel) printExtensionBlock(evt app.ExtensionPrintEvent) tea.Cmd {
 		WithBorderColor(borderClr),
 		WithMarginBottom(1),
 	)
-	return tea.Println(rendered)
+	m.appendScrollback(rendered)
 }
 
 // handleExtensionCommand checks if the submitted text matches an extension-
@@ -1916,7 +1939,7 @@ func (m *AppModel) handleExtensionCommand(text string) tea.Cmd {
 }
 
 // printHelpMessage renders the help text listing all available slash commands.
-func (m *AppModel) printHelpMessage() tea.Cmd {
+func (m *AppModel) printHelpMessage() {
 	help := "## Available Commands\n\n" +
 		"**Info:**\n" +
 		"- `/help`: Show this help message\n" +
@@ -1966,11 +1989,11 @@ func (m *AppModel) printHelpMessage() tea.Cmd {
 		"- `Ctrl+C`: Exit at any time\n" +
 		"- `ESC` (x2): Cancel ongoing LLM generation\n\n" +
 		"You can also just type your message to chat with the AI assistant."
-	return m.printSystemMessage(help)
+	m.printSystemMessage(help)
 }
 
 // printToolsMessage renders the list of available tools.
-func (m *AppModel) printToolsMessage() tea.Cmd {
+func (m *AppModel) printToolsMessage() {
 	var content string
 	content = "## Available Tools\n\n"
 	if len(m.toolNames) == 0 {
@@ -1980,11 +2003,11 @@ func (m *AppModel) printToolsMessage() tea.Cmd {
 			content += fmt.Sprintf("%d. `%s`\n", i+1, tool)
 		}
 	}
-	return m.printSystemMessage(content)
+	m.printSystemMessage(content)
 }
 
 // printServersMessage renders the list of configured MCP servers.
-func (m *AppModel) printServersMessage() tea.Cmd {
+func (m *AppModel) printServersMessage() {
 	var content string
 	content = "## Configured MCP Servers\n\n"
 	if len(m.serverNames) == 0 {
@@ -1994,13 +2017,14 @@ func (m *AppModel) printServersMessage() tea.Cmd {
 			content += fmt.Sprintf("%d. `%s`\n", i+1, server)
 		}
 	}
-	return m.printSystemMessage(content)
+	m.printSystemMessage(content)
 }
 
 // printUsageMessage renders token usage statistics.
-func (m *AppModel) printUsageMessage() tea.Cmd {
+func (m *AppModel) printUsageMessage() {
 	if m.usageTracker == nil {
-		return m.printSystemMessage("Usage tracking is not available for this model.")
+		m.printSystemMessage("Usage tracking is not available for this model.")
+		return
 	}
 
 	sessionStats := m.usageTracker.GetSessionStats()
@@ -2014,16 +2038,17 @@ func (m *AppModel) printUsageMessage() tea.Cmd {
 	content += fmt.Sprintf("**Session Total:** %d input + %d output tokens = $%.6f (%d requests)\n",
 		sessionStats.TotalInputTokens, sessionStats.TotalOutputTokens, sessionStats.TotalCost, sessionStats.RequestCount)
 
-	return m.printSystemMessage(content)
+	m.printSystemMessage(content)
 }
 
 // printResetUsage resets usage statistics and prints a confirmation.
-func (m *AppModel) printResetUsage() tea.Cmd {
+func (m *AppModel) printResetUsage() {
 	if m.usageTracker == nil {
-		return m.printSystemMessage("Usage tracking is not available for this model.")
+		m.printSystemMessage("Usage tracking is not available for this model.")
+		return
 	}
 	m.usageTracker.Reset()
-	return m.printSystemMessage("Usage statistics have been reset.")
+	m.printSystemMessage("Usage statistics have been reset.")
 }
 
 // handleCompactCommand starts an async compaction. It returns a tea.Cmd that
@@ -2033,23 +2058,26 @@ func (m *AppModel) printResetUsage() tea.Cmd {
 // prompt (e.g. "Focus on the API design decisions").
 func (m *AppModel) handleCompactCommand(customInstructions string) tea.Cmd {
 	if m.appCtrl == nil {
-		return m.printSystemMessage("Compaction is not available.")
+		m.printSystemMessage("Compaction is not available.")
+		return nil
 	}
 	if err := m.appCtrl.CompactConversation(customInstructions); err != nil {
-		return m.printSystemMessage(fmt.Sprintf("Cannot compact: %v", err))
+		m.printSystemMessage(fmt.Sprintf("Cannot compact: %v", err))
+		return nil
 	}
 	// Transition to working state so the spinner shows while compaction runs.
 	m.state = stateWorking
+	m.printSystemMessage("Compacting conversation...")
 	var spinnerCmd tea.Cmd
 	if m.stream != nil {
 		_, spinnerCmd = m.stream.Update(app.SpinnerEvent{Show: true})
 	}
-	return tea.Batch(m.printSystemMessage("Compacting conversation..."), spinnerCmd)
+	return spinnerCmd
 }
 
 // printCompactResult renders the compaction summary in a styled block with
-// a distinct border color and a stats subtitle.
-func (m *AppModel) printCompactResult(evt app.CompactCompleteEvent) tea.Cmd {
+// a distinct border color and a stats subtitle into the scrollback buffer.
+func (m *AppModel) printCompactResult(evt app.CompactCompleteEvent) {
 	theme := GetTheme()
 
 	saved := evt.OriginalTokens - evt.CompactedTokens
@@ -2071,32 +2099,89 @@ func (m *AppModel) printCompactResult(evt app.CompactCompleteEvent) tea.Cmd {
 		WithBorderColor(theme.Secondary),
 		WithMarginBottom(1),
 	)
-	return tea.Println(rendered)
+	m.appendScrollback(rendered)
 }
 
-// flushStreamContent gets the rendered content from the stream component,
-// emits it above the BT region via tea.Println, and resets the stream. This
-// is called before printing tool calls (streaming completes before tools fire)
-// and on step completion.
-//
-// After flushing, a ClearScreen is issued to force a full terminal redraw.
-// When
-// the stream content is moved to scrollback the view height shrinks, and
-// bubbletea's inline renderer doesn't clear the orphaned terminal rows
-// below the managed region. ClearScreen ensures a clean redraw.
-func (m *AppModel) flushStreamContent() tea.Cmd {
+// flushStreamContent moves rendered content from the stream component into the
+// scrollback buffer and resets the stream. Called before tool calls (streaming
+// completes before tools fire). The actual tea.Println is deferred to
+// drainScrollback() at the end of the Update cycle.
+func (m *AppModel) flushStreamContent() {
 	if m.stream == nil {
-		return nil
+		return
 	}
 	content := m.stream.GetRenderedContent()
 	if content == "" {
-		return nil
+		return
 	}
 	m.stream.Reset()
-	return tea.Sequence(
-		tea.Println(content),
-		func() tea.Msg { return tea.ClearScreen() },
-	)
+	m.appendScrollback(content)
+}
+
+// flushStreamAndPendingUserMessages moves the previous assistant response and
+// any pending queued user messages into the scrollback buffer. Called from
+// SpinnerEvent{Show: true} where all previous stream chunks are guaranteed to
+// have been processed. The actual tea.Println is deferred to drainScrollback().
+func (m *AppModel) flushStreamAndPendingUserMessages() {
+	// 1. Flush previous stream content (assistant response).
+	if m.stream != nil {
+		if content := m.stream.GetRenderedContent(); content != "" {
+			m.stream.Reset()
+			m.appendScrollback(content)
+		}
+	}
+
+	// 2. Render pending user messages from the queue.
+	for _, text := range m.pendingUserPrints {
+		rendered := m.renderer.RenderUserMessage(text, time.Now()).Content
+		m.appendScrollback(rendered)
+	}
+	m.pendingUserPrints = nil
+}
+
+// appendScrollback adds rendered content to the scrollback buffer. The content
+// will be emitted via tea.Println when drainScrollback is called at the end of
+// the current Update cycle.
+func (m *AppModel) appendScrollback(content string) {
+	if content != "" {
+		m.scrollbackBuf = append(m.scrollbackBuf, content)
+	}
+}
+
+// drainScrollback flushes the scrollback buffer into a single tea.Println. If
+// the stream component has unflushed content, it is automatically prepended so
+// that new messages always appear below the previous assistant response. When
+// stream content is flushed a ClearScreen follows to clean up orphaned terminal
+// rows left after the view height shrinks. Returns nil if there is nothing to
+// print.
+func (m *AppModel) drainScrollback() tea.Cmd {
+	if len(m.scrollbackBuf) == 0 {
+		return nil
+	}
+
+	var parts []string
+	needsClear := false
+
+	// Auto-flush any stream content so it appears before new messages.
+	if m.stream != nil {
+		if content := m.stream.GetRenderedContent(); content != "" {
+			m.stream.Reset()
+			parts = append(parts, content)
+			needsClear = true
+		}
+	}
+
+	parts = append(parts, m.scrollbackBuf...)
+	m.scrollbackBuf = m.scrollbackBuf[:0]
+
+	printCmd := tea.Println(strings.Join(parts, "\n"))
+	if needsClear {
+		return tea.Sequence(
+			printCmd,
+			func() tea.Msg { return tea.ClearScreen() },
+		)
+	}
+	return printCmd
 }
 
 // distributeHeight recalculates child component heights after a window resize,
@@ -2242,7 +2327,8 @@ func remapKey(name string) (tea.KeyPressMsg, bool) {
 // to that model directly.
 func (m *AppModel) handleModelCommand(args string) tea.Cmd {
 	if m.setModel == nil {
-		return m.printSystemMessage("Model switching is not available.")
+		m.printSystemMessage("Model switching is not available.")
+		return nil
 	}
 
 	if args == "" {
@@ -2256,7 +2342,8 @@ func (m *AppModel) handleModelCommand(args string) tea.Cmd {
 	// Direct model switch with the provided model string.
 	previousModel := m.providerName + "/" + m.modelName
 	if err := m.setModel(args); err != nil {
-		return m.printSystemMessage(fmt.Sprintf("Failed to switch model: %v", err))
+		m.printSystemMessage(fmt.Sprintf("Failed to switch model: %v", err))
+		return nil
 	}
 
 	// Update display state directly (cannot use prog.Send from Update).
@@ -2273,7 +2360,8 @@ func (m *AppModel) handleModelCommand(args string) tea.Cmd {
 		go emit(newModel, prev, "user")
 	}
 
-	return m.printSystemMessage(fmt.Sprintf("Switched to %s", args))
+	m.printSystemMessage(fmt.Sprintf("Switched to %s", args))
+	return nil
 }
 
 // --------------------------------------------------------------------------
@@ -2285,7 +2373,8 @@ func (m *AppModel) handleModelCommand(args string) tea.Cmd {
 // minimal, low, medium, high) it switches to that level.
 func (m *AppModel) handleThinkingCommand(args string) tea.Cmd {
 	if !m.isReasoningModel {
-		return m.printSystemMessage("Current model does not support thinking/reasoning.")
+		m.printSystemMessage("Current model does not support thinking/reasoning.")
+		return nil
 	}
 
 	if args == "" {
@@ -2300,13 +2389,15 @@ func (m *AppModel) handleThinkingCommand(args string) tea.Cmd {
 			lines = append(lines, fmt.Sprintf("%s%s — %s", marker, l, models.ThinkingLevelDescription(l)))
 		}
 		header := fmt.Sprintf("Current thinking level: %s\n\nAvailable levels:", m.thinkingLevel)
-		return m.printSystemMessage(header + "\n" + strings.Join(lines, "\n"))
+		m.printSystemMessage(header + "\n" + strings.Join(lines, "\n"))
+		return nil
 	}
 
 	// Parse and validate the level.
 	level := models.ParseThinkingLevel(args)
 	if string(level) != strings.ToLower(args) {
-		return m.printSystemMessage(fmt.Sprintf("Unknown thinking level: %q. Use: off, minimal, low, medium, high", args))
+		m.printSystemMessage(fmt.Sprintf("Unknown thinking level: %q. Use: off, minimal, low, medium, high", args))
+		return nil
 	}
 
 	// Apply the change.
@@ -2316,7 +2407,8 @@ func (m *AppModel) handleThinkingCommand(args string) tea.Cmd {
 			_ = m.setThinkingLevel(string(level))
 		}()
 	}
-	return m.printSystemMessage(fmt.Sprintf("Thinking level set to: %s — %s", level, models.ThinkingLevelDescription(level)))
+	m.printSystemMessage(fmt.Sprintf("Thinking level set to: %s — %s", level, models.ThinkingLevelDescription(level)))
+	return nil
 }
 
 // --------------------------------------------------------------------------
@@ -2327,10 +2419,12 @@ func (m *AppModel) handleThinkingCommand(args string) tea.Cmd {
 func (m *AppModel) handleTreeCommand() tea.Cmd {
 	ts := m.appCtrl.GetTreeSession()
 	if ts == nil {
-		return m.printSystemMessage("No tree session active. Start with `--continue` or `--resume` to enable tree sessions.")
+		m.printSystemMessage("No tree session active. Start with `--continue` or `--resume` to enable tree sessions.")
+		return nil
 	}
 	if ts.EntryCount() == 0 {
-		return m.printSystemMessage("No entries in session yet.")
+		m.printSystemMessage("No entries in session yet.")
+		return nil
 	}
 
 	m.treeSelector = NewTreeSelector(ts, m.width, m.height)
@@ -2343,10 +2437,12 @@ func (m *AppModel) handleTreeCommand() tea.Cmd {
 func (m *AppModel) handleForkCommand() tea.Cmd {
 	ts := m.appCtrl.GetTreeSession()
 	if ts == nil {
-		return m.printSystemMessage("No tree session active. Start with `--continue` or `--resume` to enable tree sessions.")
+		m.printSystemMessage("No tree session active. Start with `--continue` or `--resume` to enable tree sessions.")
+		return nil
 	}
 	if ts.EntryCount() == 0 {
-		return m.printSystemMessage("No entries to fork from.")
+		m.printSystemMessage("No entries to fork from.")
+		return nil
 	}
 
 	m.treeSelector = NewTreeSelector(ts, m.width, m.height)
@@ -2384,14 +2480,16 @@ func (m *AppModel) performNewSession() tea.Cmd {
 		if m.appCtrl != nil {
 			m.appCtrl.ClearMessages()
 		}
-		return m.printSystemMessage("Conversation cleared. Starting fresh.")
+		m.printSystemMessage("Conversation cleared. Starting fresh.")
+		return nil
 	}
 
 	ts.ResetLeaf()
 	if m.appCtrl != nil {
 		m.appCtrl.ClearMessages()
 	}
-	return m.printSystemMessage("New branch started. Previous conversation is preserved in the tree.")
+	m.printSystemMessage("New branch started. Previous conversation is preserved in the tree.")
+	return nil
 }
 
 // performFork performs the actual tree branch. Called either directly (when no
@@ -2399,7 +2497,8 @@ func (m *AppModel) performNewSession() tea.Cmd {
 func (m *AppModel) performFork(targetID string, isUser bool, userText string) tea.Cmd {
 	ts := m.appCtrl.GetTreeSession()
 	if ts == nil {
-		return m.printSystemMessage("No tree session active.")
+		m.printSystemMessage("No tree session active.")
+		return nil
 	}
 
 	_ = ts.Branch(targetID)
@@ -2413,7 +2512,7 @@ func (m *AppModel) performFork(targetID string, isUser bool, userText string) te
 		}
 	}
 
-	return m.printSystemMessage(
+	m.printSystemMessage(
 		fmt.Sprintf("Navigated to branch point. %s",
 			func() string {
 				if isUser {
@@ -2421,29 +2520,34 @@ func (m *AppModel) performFork(targetID string, isUser bool, userText string) te
 				}
 				return "Continue from this point."
 			}()))
+	return nil
 }
 
 // handleNameCommand sets a display name for the current session.
 func (m *AppModel) handleNameCommand() tea.Cmd {
 	ts := m.appCtrl.GetTreeSession()
 	if ts == nil {
-		return m.printSystemMessage("No tree session active.")
+		m.printSystemMessage("No tree session active.")
+		return nil
 	}
 	// For now, prompt user to provide name via input. We print instructions
 	// and the next non-command input starting with "name:" will be captured.
 	// TODO: inline input dialog.
 	currentName := ts.GetSessionName()
 	if currentName != "" {
-		return m.printSystemMessage(fmt.Sprintf("Current session name: %q\nTo rename, type: `/name <new name>` (not yet implemented — use the session file directly).", currentName))
+		m.printSystemMessage(fmt.Sprintf("Current session name: %q\nTo rename, type: `/name <new name>` (not yet implemented — use the session file directly).", currentName))
+		return nil
 	}
-	return m.printSystemMessage("To name this session, use: `/name <new name>` (not yet implemented — use the session file directly).")
+	m.printSystemMessage("To name this session, use: `/name <new name>` (not yet implemented — use the session file directly).")
+	return nil
 }
 
 // handleSessionInfoCommand shows session statistics.
 func (m *AppModel) handleSessionInfoCommand() tea.Cmd {
 	ts := m.appCtrl.GetTreeSession()
 	if ts == nil {
-		return m.printSystemMessage("No tree session active.")
+		m.printSystemMessage("No tree session active.")
+		return nil
 	}
 
 	header := ts.GetHeader()
@@ -2468,7 +2572,8 @@ func (m *AppModel) handleSessionInfoCommand() tea.Cmd {
 		info += fmt.Sprintf("- **Name:** %s\n", name)
 	}
 
-	return m.printSystemMessage(info)
+	m.printSystemMessage(info)
+	return nil
 }
 
 // --------------------------------------------------------------------------
@@ -2779,8 +2884,7 @@ func (m *AppModel) handleShellCommandResult(msg shellCommandResultMsg) tea.Cmd {
 		WithMarginBottom(1),
 	)
 
-	var cmds []tea.Cmd
-	cmds = append(cmds, tea.Println(rendered))
+	m.appendScrollback(rendered)
 
 	// For ! (included in context): inject the command output into the
 	// conversation as a user message so the LLM can reference it on the
@@ -2800,5 +2904,5 @@ func (m *AppModel) handleShellCommandResult(msg shellCommandResultMsg) tea.Cmd {
 		m.appCtrl.AddContextMessage(contextMsg)
 	}
 
-	return tea.Batch(cmds...)
+	return nil
 }

internal/ui/model_test.go

@@ -405,14 +405,16 @@ func TestQueuedMessages_storedOnQueuedSubmit(t *testing.T) {
 }
 
 // TestQueuedMessages_poppedOnQueueUpdated verifies that QueueUpdatedEvent pops
-// consumed messages from queuedMessages and prints them to scrollback.
+// consumed messages from queuedMessages and moves them to pendingUserPrints.
+// The actual printing is deferred to SpinnerEvent{Show: true} to preserve
+// chronological order with the preceding assistant response.
 func TestQueuedMessages_poppedOnQueueUpdated(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
 	m.queuedMessages = []string{"first", "second", "third"}
 
 	// Simulate drainQueue popping one item (length goes from 3 to 2).
-	_, cmd := m.Update(app.QueueUpdatedEvent{Length: 2})
+	m = sendMsg(m, app.QueueUpdatedEvent{Length: 2})
 
 	if len(m.queuedMessages) != 2 {
 		t.Fatalf("expected 2 queued messages after pop, got %d", len(m.queuedMessages))
@@ -420,14 +422,17 @@ func TestQueuedMessages_poppedOnQueueUpdated(t *testing.T) {
 	if m.queuedMessages[0] != "second" {
 		t.Fatalf("expected first remaining message 'second', got %q", m.queuedMessages[0])
 	}
-	// Should produce a cmd (tea.Println for the popped user message).
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd (tea.Println) for popped message")
+	// Popped message should be deferred to pendingUserPrints.
+	if len(m.pendingUserPrints) != 1 {
+		t.Fatalf("expected 1 pending user print, got %d", len(m.pendingUserPrints))
+	}
+	if m.pendingUserPrints[0] != "first" {
+		t.Fatalf("expected pending message 'first', got %q", m.pendingUserPrints[0])
 	}
 }
 
 // TestQueuedMessages_allPoppedOnDrain verifies that QueueUpdatedEvent with
-// Length=0 pops all remaining queued messages.
+// Length=0 pops all remaining queued messages into pendingUserPrints.
 func TestQueuedMessages_allPoppedOnDrain(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
@@ -438,6 +443,9 @@ func TestQueuedMessages_allPoppedOnDrain(t *testing.T) {
 	if len(m.queuedMessages) != 0 {
 		t.Fatalf("expected 0 queued messages after drain, got %d", len(m.queuedMessages))
 	}
+	if len(m.pendingUserPrints) != 2 {
+		t.Fatalf("expected 2 pending user prints, got %d", len(m.pendingUserPrints))
+	}
 }
 
 // --------------------------------------------------------------------------

internal/ui/prompt.go

@@ -83,7 +83,7 @@ func newInputPrompt(message, placeholder, defaultValue string, width, height int
 
 	// Prevent Enter from inserting a newline — we intercept it for submit.
 	ta.KeyMap.InsertNewline = key.NewBinding(
-		key.WithKeys("ctrl+j", "alt+enter"),
+		key.WithKeys("ctrl+j", "shift+enter"),
 	)
 
 	if defaultValue != "" {

internal/ui/slash_command_input.go

@@ -42,10 +42,10 @@ func NewSlashCommandInput(width int, title string) *SlashCommandInput {
 	ta.SetHeight(3)        // Default to 3 lines like huh
 	ta.Focus()
 
-	// Override InsertNewline so only ctrl+j and alt+enter insert newlines.
+	// Override InsertNewline so only ctrl+j and shift+enter insert newlines.
 	// Enter always submits the input.
 	ta.KeyMap.InsertNewline = key.NewBinding(
-		key.WithKeys("ctrl+j", "alt+enter"),
+		key.WithKeys("ctrl+j", "shift+enter"),
 		key.WithHelp("ctrl+j", "insert newline"),
 	)
 
@@ -227,7 +227,7 @@ func (s *SlashCommandInput) View() tea.View {
 			MarginTop(1).
 			PaddingLeft(3)
 
-		helpText := "enter submit • ctrl+j / alt+enter new line"
+		helpText := "enter submit • ctrl+j / shift+enter new line"
 
 		view.WriteString("\n")
 		view.WriteString(helpStyle.Render(helpText))

internal/ui/stream.go

@@ -1,6 +1,7 @@
 package ui
 
 import (
+	"fmt"
 	"strings"
 	"time"
 
@@ -165,9 +166,15 @@ type StreamComponent struct {
 	// the cache.
 	renderDirty bool
 
-	// thinkingVisible controls whether reasoning blocks are shown or collapsed.
+	// thinkingVisible controls whether reasoning blocks are expanded or collapsed.
 	thinkingVisible bool
 
+	// reasoningStartTime records when the first reasoning chunk was received.
+	reasoningStartTime time.Time
+
+	// reasoningDuration holds the total reasoning time, frozen when streaming text begins.
+	reasoningDuration time.Duration
+
 	// messageRenderer renders assistant messages in standard mode.
 	messageRenderer *MessageRenderer
 
@@ -236,6 +243,8 @@ func (s *StreamComponent) Reset() {
 	s.renderCache = ""
 	s.renderDirty = false
 	s.timestamp = time.Time{}
+	s.reasoningStartTime = time.Time{}
+	s.reasoningDuration = 0
 }
 
 // GetRenderedContent returns the rendered assistant message from the accumulated
@@ -334,6 +343,9 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if s.timestamp.IsZero() {
 			s.timestamp = time.Now()
 		}
+		if s.reasoningStartTime.IsZero() {
+			s.reasoningStartTime = time.Now()
+		}
 		s.pendingReasoning.WriteString(msg.Delta)
 		if !s.flushPending {
 			s.flushPending = true
@@ -345,6 +357,10 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if s.timestamp.IsZero() {
 			s.timestamp = time.Now()
 		}
+		// Freeze reasoning duration on transition from reasoning to streaming.
+		if s.reasoningDuration == 0 && !s.reasoningStartTime.IsZero() {
+			s.reasoningDuration = time.Since(s.reasoningStartTime)
+		}
 		s.pendingStream.WriteString(msg.Content)
 		if !s.flushPending {
 			s.flushPending = true
@@ -432,29 +448,65 @@ func (s *StreamComponent) render() string {
 	return content
 }
 
-// renderReasoningBlock renders the reasoning/thinking content. When thinking
-// is visible, the full reasoning text is shown in muted italic style. When
-// collapsed, a "Thinking..." label is shown instead.
+// renderReasoningBlock renders the reasoning/thinking content in a surface-tinted
+// box. When collapsed, shows the last 10 lines with a truncation hint. When
+// expanded, shows all lines. Includes a "Thought for Xs" duration footer.
 func (s *StreamComponent) renderReasoningBlock(reasoning string) string {
 	theme := GetTheme()
+	maxWidth := max(s.width-4, 20)
 
-	if !s.thinkingVisible {
-		// Show collapsed "Thinking..." label.
-		return lipgloss.NewStyle().
-			Foreground(theme.Muted).
-			Italic(true).
-			Render("Thinking...")
-	}
+	lines := strings.Split(strings.TrimRight(reasoning, "\n"), "\n")
 
-	// Render full reasoning text in muted italic style.
-	style := lipgloss.NewStyle().
+	contentStyle := lipgloss.NewStyle().
 		Foreground(theme.Muted).
 		Italic(true)
 
-	// Wrap to terminal width.
-	maxWidth := max(s.width-4, 20) // leave some margin
-	styled := style.Width(maxWidth).Render(reasoning)
-	return styled
+	var parts []string
+
+	// When collapsed and content exceeds 10 lines, show only the last 10
+	// with a truncation hint (matching iteratr's thinking block pattern).
+	const maxCollapsedLines = 10
+	if !s.thinkingVisible && len(lines) > maxCollapsedLines {
+		hidden := len(lines) - maxCollapsedLines
+		hintStyle := lipgloss.NewStyle().
+			Foreground(theme.VeryMuted).
+			Italic(true)
+		parts = append(parts, hintStyle.Render(fmt.Sprintf("... (%d lines hidden)", hidden)))
+		lines = lines[len(lines)-maxCollapsedLines:]
+	}
+
+	// Render reasoning text.
+	parts = append(parts, contentStyle.Width(maxWidth).Render(strings.Join(lines, "\n")))
+
+	// Duration footer.
+	var duration time.Duration
+	if s.reasoningDuration > 0 {
+		duration = s.reasoningDuration
+	} else if !s.reasoningStartTime.IsZero() {
+		duration = time.Since(s.reasoningStartTime)
+	}
+	if duration > 0 {
+		var durationStr string
+		if duration < time.Second {
+			durationStr = fmt.Sprintf("%dms", duration.Milliseconds())
+		} else {
+			durationStr = fmt.Sprintf("%.1fs", duration.Seconds())
+		}
+		footer := lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("Thought for ") +
+			lipgloss.NewStyle().Foreground(theme.Info).Render(durationStr)
+		parts = append(parts, footer)
+	}
+
+	innerContent := strings.Join(parts, "\n")
+
+	// Wrap in box with surface background for visual distinction.
+	boxStyle := lipgloss.NewStyle().
+		Background(theme.MutedBorder). // Surface0 (#313244)
+		PaddingLeft(1).
+		Width(maxWidth + 2).
+		MarginBottom(1)
+
+	return boxStyle.Render(innerContent)
 }
 
 // SetThinkingVisible sets whether reasoning blocks are shown or collapsed.

internal/ui/usage_tracker_test.go

@@ -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

pkg/kit/events.go

@@ -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.

pkg/kit/extensions_bridge.go

@@ -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,

pkg/kit/hooks.go

@@ -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

pkg/kit/hooks_test.go

@@ -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")

pkg/kit/kit.go

@@ -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,64 @@ 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,
+			OnEvent: func(e Event) {
+				m.events.emit(e)
+			},
+		})
+		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 +1583,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 +1595,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

pkg/kit/tools.go

@@ -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...) }

skills-lock.json

@@ -5,6 +5,11 @@
       "source": "davis7dotsh/better-context",
       "sourceType": "github",
       "computedHash": "99bc5301f4f839a6f3be99d98955f32f1cd576c218731fa05fa54a003bd20e9b"
+    },
+    "kit-extensions": {
+      "source": "mark3labs/kit",
+      "sourceType": "github",
+      "computedHash": "9347a88bec46dd52727a672b6c8d058955f9f50dfe98708e0c63b85e0779ba96"
     }
   }
 }

skills/kit-extensions/SKILL.md

@@ -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