feat: in-process subagents replace subprocess spawning

Subagents now run as child Kit instances in the same process instead of
spawning a kit binary subprocess. This removes the binary dependency,
eliminates JSON serialization overhead, and enables SDK-only consumers
to use subagents without installing the kit CLI.

- Add Kit.Subagent() method for in-process subagent execution
- Add SubagentConfig/SubagentResult types to the SDK
- Add context-based SubagentSpawnFunc injection so core spawn_subagent
  tool calls back to Kit.Subagent() without an import cycle
- Add SubagentTools() bundle (all core tools minus spawn_subagent)
- Add viperInitMu for thread-safe concurrent kit.New() calls
- Wire extension ctx.SpawnSubagent and ACP server to use in-process
- Child Kit gets parent's model as fallback, in-memory or persisted
  session, and no extensions (preventing recursive loading)

.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

AGENTS.md

@@ -83,9 +83,9 @@ tmux kill-session -t kittest              # cleanup
 ### Non-Interactive Kit (Subprocess Spawning)
 Extensions can spawn Kit as a subprocess for sub-agent patterns:
 ```bash
-kit --prompt "question" --quiet --no-session --no-extensions --system-prompt /path/to/prompt.txt --model provider/model
+kit --quiet --no-session --no-extensions --system-prompt /path/to/prompt.txt --model provider/model "question"
 ```
-Key flags: `--quiet` (stdout only, no TUI), `--no-session` (ephemeral), `--no-extensions` (prevent recursive loading), `--system-prompt` (string or file path).
+Positional args are the prompt. `@file` args attach file content. Key flags: `--quiet` (stdout only, no TUI), `--no-session` (ephemeral), `--no-extensions` (prevent recursive loading), `--system-prompt` (string or file path).
 
 ## External Repo Research
 - **ALWAYS use `btca`** to search external repos (e.g. iteratr, other reference codebases)

GAP_ANALYSIS.md

@@ -1,599 +0,0 @@
-# Kit vs Pi Extension System: Comprehensive Gap Analysis
-
-> Generated: 2026-03-01
-> Source: [pi-mono extensions](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions)
-
----
-
-## Executive Summary
-
-Pi's extension ecosystem contains **57+ example extensions** spanning safety guards, git integration, custom providers, session management, resource discovery, and advanced UI patterns. Kit has **10 example extensions** and a solid foundation with 13 lifecycle events and a rich widget/overlay/editor system, but lacks several critical API surfaces that Pi exposes. The gaps fall into three tiers:
-
-- **Critical (17 gaps)**: Missing API capabilities that block entire categories of extensions
-- **Moderate (7 gaps)**: Capabilities that exist but lack depth compared to Pi
-- **Covered (14 areas)**: Capabilities where Kit has parity or near-parity
-
----
-
-## Pi Extension Inventory (57 extensions)
-
-### Safety & Lifecycle (5)
-| Extension | Description |
-|---|---|
-| `permission-gate.ts` | Confirms dangerous bash commands (rm -rf, sudo) |
-| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/) |
-| `confirm-destructive.ts` | Confirms destructive session actions (clear, fork) |
-| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git |
-| `sandbox/` | OS-level sandboxing via `@anthropic-ai/sandbox-runtime` |
-
-### Git Integration (2)
-| Extension | Description |
-|---|---|
-| `git-checkpoint.ts` | Git stash checkpoints per turn, restore on fork |
-| `auto-commit-on-exit.ts` | Auto-commits using assistant message as commit msg |
-
-### Custom Tools (11)
-| Extension | Description |
-|---|---|
-| `hello.ts` | Minimal custom tool |
-| `question.ts` | Agent-initiated user questions with custom UI |
-| `questionnaire.ts` | Multi-question tabbed tool |
-| `tool-override.ts` | Override built-in tools |
-| `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools |
-| `minimal-mode.ts` | Override all tool rendering for minimal display |
-| `truncated-tool.ts` | Ripgrep with output truncation |
-| `antigravity-image-gen.ts` | Image generation with external API |
-| `ssh.ts` | Delegate tools to remote via SSH |
-| `subagent/` | Delegate to specialized subagents |
-| `todo.ts` | Todo list tool with state persistence |
-
-### Commands & UI (25)
-| Extension | Description |
-|---|---|
-| `preset.ts` | Named presets (model, thinking, tools, instructions) |
-| `plan-mode/` | Read-only exploration with /plan command |
-| `tools.ts` | Interactive /tools to enable/disable tools |
-| `handoff.ts` | Transfer context to new session |
-| `qna.ts` | Extract questions from response into editor |
-| `commands.ts` | /commands with introspection and tab completion |
-| `model-status.ts` | Model change notifications in status bar |
-| `send-user-message.ts` | Programmatic message injection (3 modes) |
-| `timed-confirm.ts` | Auto-dismissing dialogs with AbortSignal |
-| `rpc-demo.ts` | Full UI method catalog |
-| `modal-editor.ts` | Vim-like modal editor (full editor replacement) |
-| `rainbow-editor.ts` | Animated rainbow editor |
-| `notify.ts` | Desktop OS notifications |
-| `titlebar-spinner.ts` | Terminal title animations |
-| `summarize.ts` | Conversation summarization |
-| `custom-footer.ts` | Custom footer with git branch + token stats |
-| `custom-header.ts` | Custom ASCII art header |
-| `overlay-test.ts` | Custom overlay with Focusable components |
-| `overlay-qa-tests.ts` | Comprehensive overlay QA tests |
-| `doom-overlay/` | DOOM game running as overlay |
-| `shutdown-command.ts` | /quit command via ctx.shutdown() |
-| `reload-runtime.ts` | Hot reload extensions at runtime |
-| `interactive-shell.ts` | Full terminal takeover for vim/htop |
-| `inline-bash.ts` | !{command} expansion in prompts |
-| `snake.ts` | Snake game with custom UI |
-
-### System Prompt & Compaction (4)
-| Extension | Description |
-|---|---|
-| `pirate.ts` | System prompt append |
-| `claude-rules.ts` | Project rules loader from .claude/rules/ |
-| `custom-compaction.ts` | Custom compaction with cross-model summarization |
-| `trigger-compact.ts` | Auto-trigger compaction at token threshold |
-
-### System Integration (1)
-| Extension | Description |
-|---|---|
-| `mac-system-theme.ts` | Syncs theme with macOS dark/light mode |
-
-### Resources (1)
-| Extension | Description |
-|---|---|
-| `dynamic-resources/` | Dynamic skill/prompt/theme loading |
-
-### Messages & Communication (2)
-| Extension | Description |
-|---|---|
-| `message-renderer.ts` | Custom message rendering with expandable details |
-| `event-bus.ts` | Inter-extension pub/sub communication |
-
-### Session Metadata (2)
-| Extension | Description |
-|---|---|
-| `session-name.ts` | Name sessions for selector |
-| `bookmark.ts` | Bookmark entries with labels for /tree |
-
-### Custom Providers (3)
-| Extension | Description |
-|---|---|
-| `custom-provider-anthropic/` | Custom Anthropic provider with OAuth |
-| `custom-provider-gitlab-duo/` | GitLab Duo provider |
-| `custom-provider-qwen-cli/` | Qwen CLI provider |
-
-### External Dependencies (1)
-| Extension | Description |
-|---|---|
-| `with-deps/` | Extension with own package.json |
-
----
-
-## Kit Extension Inventory (10 extensions)
-
-| Extension | Description |
-|---|---|
-| `minimal.go` | UI visibility, footer, context stats polling |
-| `widget-status.go` | Persistent widgets, OnToolResult, input commands |
-| `tool-logger.go` | Tool event logging, PrintBlock with styling |
-| `header-footer-demo.go` | Custom header/footer with slash commands |
-| `prompt-demo.go` | All 3 prompt types + chained workflow |
-| `overlay-demo.go` | Modal overlay dialogs (info, actions, markdown, scroll) |
-| `custom-editor-demo.go` | Vim-like editor interceptor |
-| `tool-renderer-demo.go` | Custom tool rendering for read/bash |
-| `subagent-widget.go` | Background subprocess agents with live widgets |
-| `kit-kit.go` | Meta-agent with parallel experts, grid widget |
-
----
-
-## Gap Analysis: Critical Gaps (Missing API Capabilities)
-
-### Gap 1: Session Management API
-**Pi has:** `ctx.sessionManager` with full conversation access
-- `getEntries()` / `getBranch()` -- Read conversation history
-- `getLeafEntry()` -- Current leaf entry
-- `getLabel(entryId)` / `pi.setLabel()` -- Entry metadata/labeling
-- `getSessionFile()` -- Session file path
-
-**Kit has:** Nothing. Extensions cannot read conversation history.
-
-**Impact:** Blocks auto-commit (needs last assistant message), git checkpoints (needs entry IDs), handoff (needs full conversation), QnA extraction, state restoration on session resume, bookmark labeling.
-
-**Implementation approach:**
-- Add `GetMessages func() []MessageEntry` to `Context` returning conversation messages
-- Add `GetCurrentEntryID func() string` for session tree position
-- Add `SetLabel func(entryId, label string)` / `GetLabel func(entryId string) string`
-- Wire in `cmd/root.go` via closures reading from the session store
-
----
-
-### Gap 2: Model Management API
-**Pi has:**
-- `ctx.modelRegistry.find(provider, model)` -- Look up models
-- `ctx.modelRegistry.getApiKey(model)` -- Get API keys
-- `pi.setModel(model)` -- Change active model at runtime
-- `pi.setThinkingLevel(level)` -- Set reasoning budget
-
-**Kit has:** `ctx.Model string` (read-only model name)
-
-**Impact:** Blocks preset system (model switching), custom compaction (cross-model calls), QnA extraction (direct LLM calls), any extension needing to invoke a different model.
-
-**Implementation approach:**
-- Add `SetModel func(provider, model string) error` to `Context`
-- Add `GetAvailableModels func() []ModelInfo` returning provider/model/context info
-- Add `GetAPIKey func(provider string) string` for credential access
-- Add `SetThinkingLevel func(level string)` for reasoning budget control
-- Wire through to the existing `llm.Provider` interface
-
----
-
-### Gap 3: Tool Management API
-**Pi has:**
-- `pi.getAllTools()` -- List all registered tools
-- `pi.setActiveTools(names)` -- Enable/disable specific tools
-
-**Kit has:** Nothing for tool introspection or filtering.
-
-**Impact:** Blocks plan-mode (restricts tools to read-only set), preset system (tool filtering), /tools interactive toggle, any policy-based tool restriction.
-
-**Implementation approach:**
-- Add `GetAllTools func() []ToolInfo` to `Context` with name, description, enabled status
-- Add `SetActiveTools func(names []string)` to filter which tools the LLM can use
-- Add `IsToolEnabled func(name string) bool` for individual checks
-- Integrate with the existing tool wrapper pipeline in `wrapper.go`
-
----
-
-### Gap 4: Session Lifecycle Events (Before-hooks with Cancel)
-**Pi has:**
-- `session_before_switch` -- Can cancel session switching
-- `session_before_fork` -- Can cancel forking
-- `session_switch` -- React to session changes
-
-**Kit has:** `OnSessionStart` and `OnSessionShutdown` only. No before-hooks, no cancel capability, no fork/branch events.
-
-**Impact:** Blocks dirty-repo-guard, confirm-destructive, git-checkpoint (restore on fork), any defensive workflow that needs to gate session operations.
-
-**Implementation approach:**
-- Add `OnSessionBeforeSwitch` event with `SessionBeforeSwitchResult{Cancel bool, Reason string}`
-- Add `OnSessionBeforeFork` event with similar cancel capability
-- Add `OnSessionSwitch` event for post-switch notifications
-- Emit these from session management code before performing operations
-
----
-
-### Gap 5: Compaction Events
-**Pi has:** `session_before_compact` allowing custom compaction strategies (e.g., summarize entire conversation with a cheaper model instead of truncating).
-
-**Kit has:** Nothing.
-
-**Impact:** Blocks custom-compaction and trigger-compact patterns. Users cannot customize how context compaction works.
-
-**Implementation approach:**
-- Add `OnBeforeCompact` event with `BeforeCompactEvent{EstimatedTokens, ContextLimit int}`
-- Result type: `BeforeCompactResult{Summary *string, FirstKeptEntryID *string}`
-- If extension returns a summary, use it instead of default compaction
-- Add `TriggerCompact func()` to `Context` for manual compaction triggers
-
----
-
-### Gap 6: Custom Provider Registration
-**Pi has:** `pi.registerProvider()` allowing extensions to register complete LLM providers with streaming, OAuth, and model definitions.
-
-**Kit has:** No extension-facing provider registration. Providers are compiled-in via the `llm.Provider` interface.
-
-**Impact:** Blocks custom-provider-anthropic, custom-provider-gitlab-duo, custom-provider-qwen-cli patterns. Users cannot add new LLM backends via extensions.
-
-**Implementation approach:**
-- Add `RegisterProvider(ProviderDef)` to `API` with:
-  - `Name string`, `Models []ModelDef`
-  - `Stream func(model, messages, options) StreamResult`
-- This is a large undertaking. The `ProviderDef` would need to bridge to the compiled `llm.Provider` interface.
-- **Yaegi limitation:** Complex streaming interfaces may hit Yaegi's interface generation bugs. May need concrete struct wrappers.
-- **Priority:** Lower -- this is architecturally complex and has narrow use cases.
-
----
-
-### Gap 7: CLI Flag Registration
-**Pi has:** `pi.registerFlag("preset", {description, type})` and `pi.getFlag("preset")` allowing extensions to add CLI flags.
-
-**Kit has:** Nothing. Extensions cannot influence CLI argument parsing.
-
-**Impact:** Blocks preset system (--preset flag), plan-mode (--plan flag), sandbox (--no-sandbox flag).
-
-**Implementation approach:**
-- Add `RegisterFlag(FlagDef)` to `API` with `Name, Description, Type string, Default any`
-- Add `GetFlag func(name string) any` to `Context`
-- Parse extension flags after loading extensions but before `Init()`
-- Store in a `map[string]any` on the Runner
-
----
-
-### Gap 8: Keyboard Shortcut Registration
-**Pi has:** `pi.registerShortcut(Key.ctrlShift("u"), {description, handler})` for global keyboard shortcuts.
-
-**Kit has:** Nothing. Only editor interceptors can handle keys, and only when the editor has focus.
-
-**Impact:** Blocks global shortcuts like Ctrl+Alt+P for plan mode toggle, Ctrl+Shift+U for preset switching.
-
-**Implementation approach:**
-- Add `RegisterShortcut(ShortcutDef)` to `API` with `Key string, Description string, Handler func(Context)`
-- Bridge to BubbleTea's key handling in `model.go` Update() method
-- Query registered shortcuts from Runner in the key dispatch path
-
----
-
-### Gap 9: Custom Message Rendering
-**Pi has:** `pi.registerMessageRenderer(customType, renderFn)` for custom visual rendering of specific message types (not just tool results).
-
-**Kit has:** `RegisterToolRenderer` for tool-specific rendering only. No general message renderer.
-
-**Impact:** Blocks status-update messages, extension-branded messages, and any custom message type that needs bespoke visual treatment.
-
-**Implementation approach:**
-- Add `RegisterMessageRenderer(MessageRenderConfig)` to `API` with:
-  - `CustomType string` -- message type to match
-  - `Render func(content, details string, expanded bool, width int) string`
-- Integrate with the stream component's message rendering pipeline
-
----
-
-### Gap 10: Programmatic Editor Control
-**Pi has:**
-- `ctx.ui.setEditorText(text)` -- Pre-fill the input editor
-- `ctx.ui.setEditorComponent(factory)` -- Replace the entire editor
-
-**Kit has:** `SetEditor(EditorConfig)` which is an interceptor (HandleKey/Render) but does NOT allow setting editor text or full replacement.
-
-**Impact:** Blocks QnA (pre-fill editor with extracted questions), handoff (pre-fill with handoff prompt), and full editor replacement patterns.
-
-**Implementation approach:**
-- Add `SetEditorText func(text string)` to `Context` -- inserts text into the active editor
-- Optionally add `SetEditorComponent func(EditorComponentConfig)` for full replacement (complex due to BubbleTea integration)
-
----
-
-### Gap 11: Turn-Level Events
-**Pi has:**
-- `turn_start` -- Fires when a new LLM turn begins
-- `turn_end` -- Fires when a turn completes
-
-**Kit has:** `OnAgentStart`/`OnAgentEnd` which fire at the agent loop level (may span multiple turns), and `OnMessageStart`/`OnMessageEnd` for streaming. No dedicated turn boundary events.
-
-**Impact:** Blocks git-checkpoint (create stash per turn), plan-mode (track done markers per turn), preset (persist state per turn), progress tracking.
-
-**Implementation approach:**
-- Add `OnTurnStart(func(TurnStartEvent, Context))` and `OnTurnEnd(func(TurnEndEvent, Context))`
-- `TurnStartEvent{TurnNumber int, Prompt string}`
-- `TurnEndEvent{TurnNumber int, Response string, StopReason string}`
-- Emit from the agent loop between turns
-
----
-
-### Gap 12: Context Filtering Event
-**Pi has:** `pi.on("context", ...)` -- Lets extensions filter/modify messages before sending to the LLM. Returns `{messages: [...]}` to replace the context window.
-
-**Kit has:** Nothing. Extensions cannot influence what messages the LLM sees.
-
-**Impact:** Blocks plan-mode (filter stale messages), any extension needing to manage context window content, RAG-style context injection.
-
-**Implementation approach:**
-- Add `OnContextPrepare(func(ContextPrepareEvent, Context) *ContextPrepareResult)`
-- `ContextPrepareEvent{Messages []MessageEntry}`
-- `ContextPrepareResult{Messages []MessageEntry}` -- return filtered/modified set
-- Emit just before sending messages to the LLM provider
-
----
-
-### Gap 13: Inter-Extension Event Bus
-**Pi has:** `pi.events.on(name, handler)` / `pi.events.emit(name, data)` for decoupled inter-extension communication.
-
-**Kit has:** Nothing. Extensions are isolated; they cannot communicate with each other.
-
-**Impact:** Blocks coordinated multi-extension workflows (e.g., theme extension reacting to mode changes from another extension).
-
-**Implementation approach:**
-- Add `OnCustomEvent func(name string, handler func(data string))` to `API`
-- Add `EmitCustomEvent func(name, data string)` to `Context`
-- Store handlers in Runner's event map, dispatch via `Emit`
-
----
-
-### Gap 14: Session Persistence for Extensions
-**Pi has:** `pi.appendEntry(customType, data)` -- Persists extension-specific data in the session journal. Survives across session resume.
-
-**Kit has:** Nothing. Extension state is ephemeral (package-level vars lost on restart).
-
-**Impact:** Blocks preset state restoration, plan-mode progress persistence, todo list persistence across sessions, any extension needing durable state.
-
-**Implementation approach:**
-- Add `AppendEntry func(entryType string, data string)` to `Context`
-- Add `GetEntries func(entryType string) []string` to `Context` for retrieval
-- Store in session file as custom entry types
-- Emit entries during `OnSessionStart` for restoration
-
----
-
-### Gap 15: Resource Discovery System
-**Pi has:** `resources_discover` event where extensions can dynamically register skills, prompts, and themes by returning file paths.
-
-**Kit has:** Nothing. No concept of dynamic resource loading.
-
-**Impact:** Blocks dynamic-resources pattern. Extensions cannot contribute prompts, skills, or themes at runtime.
-
-**Implementation approach:**
-- Add `OnResourceDiscovery(func(ResourceDiscoveryEvent, Context) *ResourceDiscoveryResult)`
-- `ResourceDiscoveryResult{SkillPaths, PromptPaths, ThemePaths []string}`
-- Integrate with any future resource/skill loading system
-
----
-
-### Gap 16: Programmatic Shutdown and Reload
-**Pi has:**
-- `ctx.shutdown()` -- Programmatically quit the application
-- `ctx.reload()` -- Hot-reload all extensions at runtime
-
-**Kit has:** Neither capability.
-
-**Impact:** Blocks shutdown-command, reload-runtime patterns. Extensions cannot control app lifecycle.
-
-**Implementation approach:**
-- Add `Shutdown func()` to `Context` -- triggers graceful shutdown
-- Add `Reload func() error` to `Context` -- reloads all extensions
-- Wire via BubbleTea Quit msg and loader re-initialization
-
----
-
-### Gap 17: Direct LLM Completion from Extensions
-**Pi has:** Extensions can call `complete()` from `@mariozechner/pi-ai` to make LLM calls outside the main agent loop (e.g., summarization, question extraction, handoff generation).
-
-**Kit has:** No way for extensions to invoke LLM completions directly. Extensions can only spawn Kit subprocesses.
-
-**Impact:** Blocks in-process LLM calls for summarization, QnA extraction, context transfer. The subprocess pattern works but is heavier.
-
-**Implementation approach:**
-- Add `Complete func(CompleteRequest) (string, error)` to `Context`
-- `CompleteRequest{Model, SystemPrompt string, Messages []SimpleMessage}`
-- Wire through to existing `llm.Provider.Complete()` method
-- Consider rate limiting and cost awareness
-
----
-
-## Gap Analysis: Moderate Gaps (Partial Coverage)
-
-### Gap M1: Tool Registration Depth
-**Pi has:** `renderCall(args, theme)`, `renderResult(result, {expanded, isPartial}, theme)` directly on tool definition. Also `onUpdate` streaming callback, `AbortSignal`, and TypeBox schemas.
-
-**Kit has:** Separate `RegisterToolRenderer()` and simpler `RegisterTool()` with JSON schema string and basic execute handler.
-
-**Implementation approach:** Enhance `ToolDef` with optional `RenderHeader`/`RenderBody` fields. Add `onUpdate func(string)` to execute handler for streaming tool progress. Add abort/cancel context.
-
----
-
-### Gap M2: Command Tab Completion
-**Pi has:** `getArgumentCompletions(prefix)` on command registration for tab-completing command arguments.
-
-**Kit has:** `RegisterCommand()` without completion support.
-
-**Implementation approach:** Add optional `Complete func(prefix string) []string` to `CommandDef`.
-
----
-
-### Gap M3: Keyed Status Bar Entries
-**Pi has:** `ctx.ui.setStatus(key, text)` for multiple independent status bar indicators.
-
-**Kit has:** `SetFooter(HeaderFooterConfig)` as a single custom footer, not keyed status entries.
-
-**Implementation approach:** Add `SetStatus func(key, text string)` / `RemoveStatus func(key string)` to `Context`. Render all keyed entries in the status bar region.
-
----
-
-### Gap M4: Full Custom TUI Components
-**Pi has:** `ctx.ui.custom<T>(factory)` where factory receives `(tui, theme, keybindings, done)` and returns a `Focusable` component. Supports overlays and full TUI takeover (including `tui.stop()`/`tui.start()` for subprocess terminal sharing).
-
-**Kit has:** `ShowOverlay(OverlayConfig)` with text content and action buttons. No way to render completely custom interactive components or suspend the TUI.
-
-**Implementation approach:**
-- This is architecturally complex with Yaegi. A simpler approach: add `SuspendTUI func(callback func())` to `Context` that stops BubbleTea, runs the callback (allowing raw terminal use), then restarts.
-- For custom overlays: enhance `OverlayConfig` with a `RenderFunc` option for custom content rendering.
-
----
-
-### Gap M5: SendMessage Delivery Modes
-**Pi has:** Three modes:
-- `pi.sendUserMessage(text)` -- Normal (triggers turn)
-- `pi.sendUserMessage(text, {deliverAs: "steer"})` -- Interrupts current stream
-- `pi.sendUserMessage(text, {deliverAs: "followUp"})` -- Queues after current stream
-
-**Kit has:** `ctx.SendMessage(string)` which queues if agent is busy (similar to followUp), but no steering/interrupt mode and no structured content.
-
-**Implementation approach:**
-- Add `SendMessageOpts{DeliverAs string}` parameter to `SendMessage`
-- Support `"steer"` (cancel current + send) and `"followUp"` (queue) modes
-- Add `SendStructuredMessage func(content []ContentBlock, opts SendMessageOpts)` for multi-part messages
-
----
-
-### Gap M6: Model Change Event
-**Pi has:** `model_select` event with `event.model`, `event.previousModel`, `event.source`.
-
-**Kit has:** No model change notification.
-
-**Implementation approach:** Add `OnModelChange(func(ModelChangeEvent, Context))` with `NewModel, PreviousModel, Source string`.
-
----
-
-### Gap M7: User Bash Hook
-**Pi has:** `user_bash` event for intercepting user-initiated `!command` invocations, separate from tool-initiated bash. Can return custom `result` to override execution.
-
-**Kit has:** No distinction between user-initiated and tool-initiated bash. `OnToolCall` catches both.
-
-**Implementation approach:** Add `OnUserBash(func(UserBashEvent, Context) *UserBashResult)` or tag `ToolCallEvent` with a `Source` field (`"user"` vs `"tool"`).
-
----
-
-## Capabilities with Parity (Covered)
-
-| Capability | Kit | Pi | Status |
-|---|---|---|---|
-| Session start/shutdown events | `OnSessionStart`, `OnSessionShutdown` | `session_start`, `session_shutdown` | Parity |
-| Before agent start (system prompt injection) | `OnBeforeAgentStart` returns `InjectText`, `SystemPrompt` | `before_agent_start` returns `systemPrompt`, `message` | Parity |
-| Agent lifecycle events | `OnAgentStart`, `OnAgentEnd` | `agent_start`, `agent_end` | Parity |
-| Message streaming events | `OnMessageStart`, `OnMessageUpdate`, `OnMessageEnd` | N/A (Pi uses `turn_start`/`turn_end` instead) | Kit advantage |
-| Tool call interception (blocking) | `OnToolCall` returns `Block`, `Reason` | `tool_call` returns `block`, `reason` | Parity |
-| Tool result modification | `OnToolResult` returns modified `Content`, `IsError` | `tool_result` returns modified content | Parity |
-| Tool execution timing | `OnToolExecutionStart`, `OnToolExecutionEnd` | N/A | Kit advantage |
-| Input interception/transform | `OnInput` returns `Action` (continue/transform/handled) | `input` returns `action` (continue/transform/handled) | Parity |
-| Custom tool registration | `RegisterTool(ToolDef)` | `pi.registerTool({...})` | Parity (Pi richer) |
-| Custom command registration | `RegisterCommand(CommandDef)` | `pi.registerCommand(name, {...})` | Parity |
-| Widget system | `SetWidget`/`RemoveWidget` with placement, priority | `setWidget(key, lines)` | Parity |
-| Header/Footer | `SetHeader`/`SetFooter` with content/style | `setHeader`/`setFooter` with factory | Parity (different models) |
-| Overlay dialogs | `ShowOverlay` with actions, scrolling, markdown | `ctx.ui.custom({overlay: true})` | Pi richer |
-| Interactive prompts | `PromptSelect`, `PromptConfirm`, `PromptInput` | `ctx.ui.select`, `ctx.ui.confirm`, `ctx.ui.input` | Parity |
-| Editor interceptor | `SetEditor(EditorConfig)` with HandleKey/Render | `setEditorComponent()` for full replacement | Pi richer |
-| Tool renderer customization | `RegisterToolRenderer(ToolRenderConfig)` | `renderCall`/`renderResult` on tool def | Parity |
-| UI visibility control | `SetUIVisibility(UIVisibility)` | N/A (Pi uses direct component replacement) | Kit advantage |
-| Context stats | `GetContextStats()` returns tokens, limit, usage% | Token data via `sessionManager.getBranch()` | Kit advantage (dedicated API) |
-| Print functions | `Print`, `PrintInfo`, `PrintError`, `PrintBlock` | `ctx.ui.notify(msg, level)` | Different models, both adequate |
-| Subprocess spawning | `os/exec` via Yaegi stdlib access | `pi.exec()` abstracted API | Parity (different approach) |
-
----
-
-## Priority-Ordered Implementation Roadmap
-
-### Phase 1: High-Impact, Lower Complexity
-These gaps block the most important extension patterns and are relatively straightforward to implement.
-
-1. **Session Management API** (Gap 1) -- Enables git integration, state restoration, bookmarks
-2. **Turn-Level Events** (Gap 11) -- Enables per-turn checkpoints and progress tracking
-3. **Session Persistence** (Gap 14) -- Enables durable extension state across restarts
-4. **Programmatic Editor Control** (Gap 10) -- Enables QnA and handoff patterns
-5. **Keyed Status Bar** (Gap M3) -- Enables richer status display
-
-### Phase 2: Medium Impact, Medium Complexity
-6. **Tool Management API** (Gap 3) -- Enables plan-mode and tool filtering
-7. **Model Management API** (Gap 2) -- Enables presets and model switching
-8. **CLI Flag Registration** (Gap 7) -- Enables --preset, --plan flags
-9. **Inter-Extension Event Bus** (Gap 13) -- Enables cross-extension coordination
-10. **SendMessage Delivery Modes** (Gap M5) -- Enables steering and follow-up patterns
-
-### Phase 3: High Impact, High Complexity
-11. **Session Lifecycle Before-Hooks** (Gap 4) -- Enables safety guards with cancel
-12. **Context Filtering Event** (Gap 12) -- Enables context management
-13. **Compaction Events** (Gap 5) -- Enables custom compaction strategies
-14. **Direct LLM Completion** (Gap 17) -- Enables in-process sub-agent calls
-15. **Full Custom TUI Components** (Gap M4) -- Enables interactive-shell, games
-
-### Phase 4: Specialized / Lower Priority
-16. **Keyboard Shortcut Registration** (Gap 8) -- Nice-to-have for power users
-17. **Custom Message Rendering** (Gap 9) -- Nice-to-have for branded messages
-18. **Custom Provider Registration** (Gap 6) -- Architecturally complex, narrow use cases
-19. **Resource Discovery** (Gap 15) -- Depends on future skill/resource system
-20. **Programmatic Shutdown/Reload** (Gap 16) -- Nice-to-have lifecycle control
-21. **Model Change Event** (Gap M6) -- Nice-to-have notification
-22. **User Bash Hook** (Gap M7) -- Nice-to-have distinction
-23. **Command Tab Completion** (Gap M2) -- Nice-to-have UX improvement
-24. **Tool Registration Depth** (Gap M1) -- Incremental improvement
-
----
-
-## Extension Ecosystem Gap: Example Extensions We Should Build
-
-Beyond API gaps, Pi simply has more example extensions demonstrating real-world patterns. Extensions we should create (once APIs exist):
-
-| Extension | Pi Equivalent | Required API Additions |
-|---|---|---|
-| Permission gate (dangerous command confirmation) | `permission-gate.ts` | None (works today with OnToolCall) |
-| Protected paths (block writes to .env, .git/) | `protected-paths.ts` | None (works today with OnToolCall) |
-| Auto-commit on exit | `auto-commit-on-exit.ts` | Gap 1 (session messages) |
-| Git checkpoints per turn | `git-checkpoint.ts` | Gaps 1, 4, 11 |
-| Desktop notifications | `notify.ts` | None (works today with OnAgentEnd + os/exec) |
-| Inline bash expansion (!{cmd}) | `inline-bash.ts` | None (works today with OnInput transform) |
-| Plan mode (read-only exploration) | `plan-mode/` | Gaps 3, 7, 11, 12, 14 |
-| Preset system | `preset.ts` | Gaps 2, 3, 7, 8, 14 |
-| Dirty repo guard | `dirty-repo-guard.ts` | Gap 4 |
-| QnA extraction | `qna.ts` | Gaps 1, 10, 17 |
-| Handoff to new session | `handoff.ts` | Gaps 1, 10, 17, 22 (newSession) |
-| Custom compaction | `custom-compaction.ts` | Gaps 2, 5 |
-| Interactive shell (vim/htop) | `interactive-shell.ts` | Gap M4 (TUI suspend) |
-| Event bus | `event-bus.ts` | Gap 13 |
-
-### Extensions Buildable Today (No API Changes Needed)
-These can be built right now with Kit's existing extension API:
-
-1. **Permission gate** -- Use `OnToolCall` to intercept bash with `rm -rf`, return `Block: true`
-2. **Protected paths** -- Use `OnToolCall` to check write/edit tool paths against deny-list
-3. **Desktop notifications** -- Use `OnAgentEnd` + `os/exec` for OSC 777 or `notify-send`
-4. **Inline bash expansion** -- Use `OnInput` with `Action: "transform"` to expand `!{cmd}`
-5. **Pirate mode** -- Use `OnBeforeAgentStart` to append to system prompt
-6. **Project rules loader** -- Use `OnSessionStart` to scan, `OnBeforeAgentStart` to inject
-7. **Titlebar spinner** -- Use `OnAgentStart`/`OnAgentEnd` + `os.Stdout` for OSC sequences
-8. **File trigger** -- Use `OnSessionStart` to set up `fsnotify` watcher, `SendMessage` to inject
-
----
-
-## Summary Statistics
-
-| Metric | Pi | Kit | Gap |
-|---|---|---|---|
-| Example extensions | 57+ | 10 | -47 |
-| Lifecycle events | 16+ | 13 | -3+ |
-| API methods on context | 35+ | 22 | -13+ |
-| Custom providers | 3 | 0 | -3 |
-| Session management APIs | 6 | 0 | -6 |
-| Model management APIs | 4 | 1 (read-only) | -3 |
-| Tool management APIs | 2 | 0 | -2 |
-| Critical API gaps | -- | -- | 17 |
-| Moderate API gaps | -- | -- | 7 |
-| Extensions buildable today | -- | -- | 8 |

README.md

@@ -13,4 +13,517 @@
 
 # KIT (Knowledge Inference Tool)
 
-TBD
+A powerful, extensible AI coding agent CLI with multi-provider support, built-in tools, and a rich extension system.
+
+## Features
+
+- **Multi-Provider LLM Support**: Anthropic, OpenAI, Google Gemini, Ollama, Azure OpenAI, AWS Bedrock, OpenRouter, and more
+- **Built-in Core Tools**: bash, read, write, edit, grep, find, ls - no MCP overhead
+- **MCP Integration**: Connect external MCP servers for expanded capabilities
+- **Extension System**: Write custom tools, commands, widgets, and UI modifications in Go
+- **Interactive TUI**: Rich terminal interface powered by Bubble Tea with streaming, syntax highlighting, and custom rendering
+- **Session Management**: Tree-based conversation history with branching support
+- **Non-Interactive Mode**: Script-friendly positional args with JSON output
+- **ACP Server**: Run Kit as an [Agent Client Protocol](https://agentclientprotocol.com) agent over stdio
+- **Go SDK**: Embed Kit in your own applications
+
+## Installation
+
+### Using npm (recommended)
+
+```bash
+npm install -g @mark3labs/kit
+```
+
+### Using Go
+
+```bash
+go install github.com/mark3labs/kit/cmd/kit@latest
+```
+
+### Building from source
+
+```bash
+git clone https://github.com/mark3labs/kit.git
+cd kit
+go build -o kit ./cmd/kit
+```
+
+## Quick Start
+
+### Basic Usage
+
+```bash
+# Start interactive session
+kit
+
+# Run a one-off prompt
+kit "List files in src/"
+
+# Attach files as context
+kit @main.go @test.go "Review these files"
+
+# Continue the most recent session
+kit --continue
+
+# Use specific model
+kit --model anthropic/claude-sonnet-4-5-20250929
+```
+
+### Non-Interactive Mode
+
+```bash
+# Get JSON output for scripting
+kit "Explain main.go" --json
+
+# Quiet mode (final response only)
+kit "Run tests" --quiet
+
+# Ephemeral mode (no session file)
+kit "Quick question" --no-session
+```
+
+### ACP Server Mode
+
+Kit can run as an [ACP (Agent Client Protocol)](https://agentclientprotocol.com) agent server, enabling ACP-compatible clients (such as [OpenCode](https://github.com/sst/opencode)) to drive Kit as a remote coding agent over stdio.
+
+```bash
+# Start Kit as an ACP server (communicates via JSON-RPC 2.0 on stdin/stdout)
+kit acp
+
+# With debug logging to stderr
+kit acp --debug
+```
+
+The ACP server exposes Kit's full capabilities — LLM execution, tool calls (bash, read, write, edit, grep, etc.), and session persistence — over the standard ACP protocol. Sessions are persisted to Kit's normal JSONL session files, so they can be resumed later.
+
+## Configuration
+
+Kit looks for configuration in the following locations (in order of priority):
+
+1. CLI flags
+2. Environment variables (with `KIT_` prefix)
+3. `./.kit.yml` (project-local)
+4. `~/.kit.yml` (global)
+
+### Basic Configuration
+
+Create `~/.kit.yml`:
+
+```yaml
+model: anthropic/claude-sonnet-4-5-20250929
+max-tokens: 4096
+temperature: 0.7
+stream: true
+```
+
+### Environment Variables
+
+```bash
+export ANTHROPIC_API_KEY="sk-..."
+export OPENAI_API_KEY="sk-..."
+export KIT_MODEL="openai/gpt-4o"
+```
+
+### MCP Server Configuration
+
+Add external MCP servers to `.kit.yml`:
+
+```yaml
+mcpServers:
+  filesystem:
+    type: local
+    command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
+    environment:
+      LOG_LEVEL: "info"
+    allowedTools: ["read_file", "write_file"]
+  
+  search:
+    type: remote
+    url: "https://mcp.example.com/search"
+```
+
+## CLI Reference
+
+### Global Flags
+
+```bash
+# Model and provider
+--model, -m              Model to use (provider/model format)
+--provider-api-key       API key for the provider
+--provider-url           Base URL for provider API
+--tls-skip-verify        Skip TLS certificate verification
+
+# Session management
+--session, -s            Open specific JSONL session file
+--continue, -c           Resume most recent session for current directory
+--resume, -r             Interactive session picker
+--no-session             Ephemeral mode, no persistence
+
+# Behavior (non-interactive: pass prompt as positional arg)
+--quiet                  Suppress all output (non-interactive only)
+--json                   Output response as JSON (non-interactive only)
+--no-exit                Enter interactive mode after prompt completes
+--max-steps              Maximum agent steps (0 for unlimited)
+--stream                 Enable streaming output (default: true)
+--compact                Enable compact output mode
+--auto-compact           Auto-compact conversation near context limit
+
+# Extensions
+--extension, -e          Load additional extension file(s) (repeatable)
+--no-extensions          Disable all extensions
+
+# Generation parameters
+--max-tokens             Maximum tokens in response (default: 4096)
+--temperature            Randomness 0.0-1.0 (default: 0.7)
+--top-p                  Nucleus sampling 0.0-1.0 (default: 0.95)
+--top-k                  Limit top K tokens (default: 40)
+--stop-sequences         Custom stop sequences (comma-separated)
+
+# System
+--config                 Config file path (default: ~/.kit.yml)
+--system-prompt          System prompt text or file path
+--debug                  Enable debug logging
+```
+
+### Commands
+
+```bash
+# Authentication (for OAuth-enabled providers)
+kit auth login           # Start OAuth flow
+kit auth logout          # Remove credentials
+kit auth status          # Check authentication status
+
+# Model database
+kit models               # List available models
+kit models --all         # Show all providers (not just Fantasy-compatible)
+kit update-models        # Update local model database from models.dev
+
+# Extension management
+kit extensions list      # List discovered extensions
+kit extensions validate  # Validate extension files
+kit extensions init      # Generate example extension template
+
+# ACP server
+kit acp                  # Start as ACP agent (stdio JSON-RPC)
+kit acp --debug          # With debug logging to stderr
+```
+
+## Extension System
+
+Extensions are Go source files that run via Yaegi interpreter. They can add custom tools, slash commands, widgets, keyboard shortcuts, and intercept lifecycle events.
+
+### Minimal Extension
+
+```go
+//go:build ignore
+
+package main
+
+import "kit/ext"
+
+func Init(api ext.API) {
+    api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+        ctx.SetFooter(ext.HeaderFooterConfig{
+            Content: ext.WidgetContent{Text: "Custom Footer"},
+        })
+    })
+}
+```
+
+**Usage:**
+
+```bash
+kit -e examples/extensions/minimal.go
+```
+
+### Extension Capabilities
+
+**Lifecycle Events**: OnSessionStart, OnSessionShutdown, OnAgentStart, OnAgentEnd, OnToolCall, OnToolResult, OnInput, OnMessageStart, OnMessageUpdate, OnMessageEnd, OnModelChange, OnContextPrepare, OnBeforeFork, OnBeforeSessionSwitch, OnBeforeCompact
+
+**Custom Components**:
+- **Tools**: Add new tools the LLM can invoke
+- **Commands**: Register slash commands (e.g., `/mycommand`)
+- **Widgets**: Persistent status displays above/below input
+- **Shortcuts**: Global keyboard shortcuts
+- **Overlays**: Modal dialogs with markdown content
+- **Tool Renderers**: Customize how tool calls display
+- **Editor Interceptors**: Handle key events and wrap rendering
+
+### Extension Examples
+
+See the `examples/extensions/` directory:
+
+- `minimal.go` - Clean UI with custom footer
+- `notify.go` - Desktop notifications
+- `widget-status.go` - Persistent status widgets
+- `custom-editor-demo.go` - Vim-like modal editor
+- `prompt-demo.go` - Interactive prompts (select/confirm/input)
+- `tool-logger.go` - Log all tool calls
+- `overlay-demo.go` - Modal dialogs
+- `plan-mode.go` - Read-only planning mode
+- `subagent-widget.go` - Multi-agent orchestration
+- `auto-commit.go` - Auto-commit on shutdown
+
+### Loading Extensions
+
+**Auto-discovery** (loads automatically):
+- `./.kit/extensions/*.go` (project-local)
+- `~/.config/kit/extensions/*.go` (global)
+
+**Explicit loading**:
+```bash
+kit -e path/to/extension.go
+kit -e ext1.go -e ext2.go  # Multiple extensions
+```
+
+**Disable auto-load**:
+```bash
+kit --no-extensions
+```
+
+## Session Management
+
+Kit uses a tree-based session model that supports branching and forking conversations.
+
+### Session Locations
+
+- Default: `~/.local/share/kit/sessions/<cwd-hash>/<uuid>.jsonl`
+- Each line is a session entry (messages, tool calls, extension data)
+- Supports branching from any message to explore alternate paths
+
+### Session Commands
+
+```bash
+# Resume most recent session for current directory
+kit --continue
+kit -c
+
+# Interactive session picker
+kit --resume
+kit -r
+
+# Open specific session file
+kit --session path/to/session.jsonl
+kit -s path/to/session.jsonl
+
+# Ephemeral mode (no file persistence)
+kit --no-session
+```
+
+## Go SDK
+
+Embed Kit in your Go applications:
+
+```go
+package main
+
+import (
+    "context"
+    "log"
+    
+    kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+func main() {
+    ctx := context.Background()
+    
+    // Create Kit instance with default configuration
+    host, err := kit.New(ctx, nil)
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer host.Close()
+    
+    // Send a prompt
+    response, err := host.Prompt(ctx, "What is 2+2?")
+    if err != nil {
+        log.Fatal(err)
+    }
+    
+    println(response)
+}
+```
+
+### With Options
+
+```go
+host, err := kit.New(ctx, &kit.Options{
+    Model:        "ollama/llama3",
+    SystemPrompt: "You are a helpful bot",
+    ConfigFile:   "/path/to/config.yml",
+    MaxSteps:     10,
+    Streaming:    true,
+    Quiet:        true,
+})
+```
+
+### With Callbacks
+
+```go
+response, err := host.PromptWithCallbacks(
+    ctx,
+    "List files in current directory",
+    func(name, args string) {
+        // Tool call started
+        println("Calling tool:", name)
+    },
+    func(name, args, result string, isError bool) {
+        // Tool call completed
+        if isError {
+            println("Tool failed:", name)
+        }
+    },
+    func(chunk string) {
+        // Streaming text chunk
+        print(chunk)
+    },
+)
+```
+
+### Session Management
+
+```go
+host.Prompt(ctx, "My name is Alice")
+response, _ := host.Prompt(ctx, "What's my name?")
+
+host.SaveSession("./session.json")
+host.LoadSession("./session.json")
+host.ClearSession()
+```
+
+## Advanced Usage
+
+### Subagent Pattern
+
+Spawn Kit as a subprocess for multi-agent orchestration:
+
+```bash
+kit "Analyze codebase" \
+    --json \
+    --no-session \
+    --no-extensions \
+    --quiet \
+    --model anthropic/claude-haiku-3-5-20241022
+```
+
+Parse the JSON output:
+
+```json
+{
+  "response": "Final assistant response text",
+  "model": "anthropic/claude-haiku-3-5-20241022",
+  "usage": {
+    "input_tokens": 1024,
+    "output_tokens": 512,
+    "total_tokens": 1536
+  },
+  "messages": [...]
+}
+```
+
+### Testing with tmux
+
+Test the TUI non-interactively:
+
+```bash
+# Start Kit in detached tmux session
+tmux new-session -d -s kittest -x 120 -y 40 \
+  "kit -e ext.go --no-session 2>kit.log"
+
+# Wait for startup
+sleep 3
+
+# Capture screen
+tmux capture-pane -t kittest -p
+
+# Send input
+tmux send-keys -t kittest '/command' Enter
+
+# Cleanup
+tmux kill-session -t kittest
+```
+
+## Development
+
+### Build and Test
+
+```bash
+# Build
+go build -o output/kit ./cmd/kit
+
+# Run tests
+go test -race ./...
+
+# Run specific test
+go test -race ./cmd -run TestScriptExecution
+
+# Lint
+go vet ./...
+
+# Format
+go fmt ./...
+```
+
+### Project Structure
+
+```
+cmd/kit/           - CLI entry point
+cmd/               - CLI command implementations
+pkg/kit/           - Go SDK
+internal/agent/    - Agent loop and tool execution
+internal/ui/       - Bubble Tea TUI components
+internal/extensions/ - Yaegi extension system
+internal/core/     - Built-in tools
+internal/tools/    - MCP tool integration
+internal/config/   - Configuration management
+internal/acpserver/ - ACP (Agent Client Protocol) server
+internal/session/  - Session persistence
+internal/models/   - Provider and model management
+examples/extensions/ - Example extension files
+```
+
+## Supported Providers
+
+- **Anthropic** - Claude models (native, prompt caching, OAuth)
+- **OpenAI** - GPT models
+- **Google** - Gemini models
+- **Ollama** - Local models
+- **Azure OpenAI** - Azure-hosted OpenAI
+- **AWS Bedrock** - Bedrock models
+- **Google Vertex** - Claude on Vertex AI
+- **OpenRouter** - Multi-provider router
+- **Vercel AI** - Vercel AI SDK models
+- **Auto-routed** - Any provider from models.dev database
+
+### Model String Format
+
+```bash
+provider/model            # Standard format
+anthropic/claude-sonnet-4-5-20250929
+openai/gpt-4o
+ollama/llama3
+google/gemini-2.0-flash-exp
+```
+
+### Model Aliases
+
+```bash
+claude-opus-latest      → claude-opus-4-20250514
+claude-sonnet-latest    → claude-sonnet-4-5-20250929
+claude-3-5-haiku-latest → claude-3-5-haiku-20241022
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[Apache 2.0](LICENSE)
+
+## Community
+
+- [Discord](https://discord.gg/RqSS2NQVsY)
+- [GitHub Issues](https://github.com/mark3labs/kit/issues)
+- [Documentation](https://github.com/mark3labs/kit/wiki)

btca.config.jsonc

@@ -64,8 +64,20 @@
       "name": "yaegi",
       "url": "https://github.com/traefik/yaegi",
       "branch": "master"
+    },
+    {
+      "type": "git",
+      "name": "acp-go-sdk",
+      "url": "https://github.com/coder/acp-go-sdk",
+      "branch": "main"
+    },
+    {
+      "type": "git",
+      "name": "opencode",
+      "url": "https://github.com/anomalyco/opencode",
+      "branch": "dev"
     }
   ],
   "model": "claude-haiku-4-5",
   "provider": "opencode"
-}
+}

cmd/acp.go

@@ -0,0 +1,159 @@
+package cmd
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	acp "github.com/coder/acp-go-sdk"
+
+	"github.com/mark3labs/kit/internal/acpserver"
+	"github.com/spf13/cobra"
+)
+
+var acpCmd = &cobra.Command{
+	Use:   "acp",
+	Short: "Start Kit as an ACP agent server",
+	Long: `Start Kit as an ACP (Agent Client Protocol) agent server.
+
+Communicates over stdio (stdin/stdout) using JSON-RPC 2.0 with
+newline-delimited JSON, compatible with OpenCode and other ACP clients.
+
+The server exposes Kit's LLM execution, tool system, and session
+management via the Agent Client Protocol. Sessions are persisted
+to Kit's standard JSONL session files.`,
+	RunE: runACP,
+}
+
+func init() {
+	rootCmd.AddCommand(acpCmd)
+}
+
+func runACP(cmd *cobra.Command, _ []string) error {
+	// Create the ACP agent implementation.
+	agent := acpserver.NewAgent()
+	defer agent.Close()
+
+	// Create the stdio connection. The SDK reads JSON-RPC from stdin and
+	// 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)
+
+	// Enable debug logging to stderr if requested.
+	if debugMode {
+		conn.SetLogger(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
+			Level: slog.LevelDebug,
+		})))
+	}
+
+	// Wait for either the client to disconnect or a signal.
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case <-conn.Done():
+		fmt.Fprintln(os.Stderr, "kit: ACP client disconnected")
+	case sig := <-sigCh:
+		fmt.Fprintf(os.Stderr, "kit: received %s, shutting down\n", sig)
+	}
+
+	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

@@ -29,7 +29,7 @@ var (
 	providerURL      string
 	providerAPIKey   string
 	debugMode        bool
-	promptFlag       string
+	positionalPrompt string // set by processPositionalArgs from CLI positional args
 	quietFlag        bool
 	jsonFlag         bool
 	noExitFlag       bool
@@ -52,6 +52,7 @@ var (
 	topP          float32
 	topK          int32
 	stopSequences []string
+	thinkingLevel string
 
 	// Ollama-specific parameters
 	numGPU  int32
@@ -101,10 +102,16 @@ func (a *kitUIAdapter) GetExtensionToolCount() int {
 // an interface to interact with various AI models through a unified interface
 // with support for MCP servers and tool integration.
 var rootCmd = &cobra.Command{
-	Use:   "kit",
+	Use:   "kit [@file...] [prompt]",
 	Short: "Chat with AI models through a unified interface",
 	Long:  `KIT (Knowledge Inference Tool) — A lightweight AI agent for coding`,
+	Args:  cobra.ArbitraryArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
+		// Parse positional args: @-prefixed args are file attachments,
+		// remaining args form the prompt (like Pi: kit @code.ts "Review this").
+		if len(args) > 0 {
+			processPositionalArgs(args)
+		}
 		return runKit(context.Background())
 	},
 }
@@ -202,14 +209,13 @@ func init() {
 			"model to use (format: provider/model)")
 	rootCmd.PersistentFlags().
 		BoolVar(&debugMode, "debug", false, "enable debug logging")
+
 	rootCmd.PersistentFlags().
-		StringVarP(&promptFlag, "prompt", "p", "", "run in non-interactive mode with the given prompt")
+		BoolVar(&quietFlag, "quiet", false, "suppress all output (non-interactive mode only)")
 	rootCmd.PersistentFlags().
-		BoolVar(&quietFlag, "quiet", false, "suppress all output (only works with --prompt)")
+		BoolVar(&jsonFlag, "json", false, "output response as JSON (non-interactive mode only)")
 	rootCmd.PersistentFlags().
-		BoolVar(&jsonFlag, "json", false, "output response as JSON (only works with --prompt)")
-	rootCmd.PersistentFlags().
-		BoolVar(&noExitFlag, "no-exit", false, "prevent non-interactive mode from exiting, show input prompt instead")
+		BoolVar(&noExitFlag, "no-exit", false, "enter interactive mode after non-interactive prompt completes")
 	rootCmd.PersistentFlags().
 		IntVar(&maxSteps, "max-steps", 0, "maximum number of agent steps (0 for unlimited)")
 	rootCmd.PersistentFlags().
@@ -242,6 +248,7 @@ func init() {
 	flags.Float32Var(&topP, "top-p", 0.95, "controls diversity via nucleus sampling (0.0-1.0)")
 	flags.Int32Var(&topK, "top-k", 40, "controls diversity by limiting top K tokens to sample from")
 	flags.StringSliceVar(&stopSequences, "stop-sequences", nil, "custom stop sequences (comma-separated)")
+	flags.StringVar(&thinkingLevel, "thinking-level", "off", "extended thinking level: off, minimal, low, medium, high")
 
 	// Ollama-specific parameters
 	flags.Int32Var(&numGPU, "num-gpu-layers", -1, "number of model layers to offload to GPU for Ollama models (-1 for auto-detect)")
@@ -252,7 +259,6 @@ func init() {
 	_ = viper.BindPFlag("system-prompt", rootCmd.PersistentFlags().Lookup("system-prompt"))
 	_ = viper.BindPFlag("model", rootCmd.PersistentFlags().Lookup("model"))
 	_ = viper.BindPFlag("debug", rootCmd.PersistentFlags().Lookup("debug"))
-	_ = viper.BindPFlag("prompt", rootCmd.PersistentFlags().Lookup("prompt"))
 	_ = viper.BindPFlag("max-steps", rootCmd.PersistentFlags().Lookup("max-steps"))
 	_ = viper.BindPFlag("stream", rootCmd.PersistentFlags().Lookup("stream"))
 	_ = viper.BindPFlag("compact", rootCmd.PersistentFlags().Lookup("compact"))
@@ -265,6 +271,7 @@ func init() {
 	_ = viper.BindPFlag("top-p", rootCmd.PersistentFlags().Lookup("top-p"))
 	_ = viper.BindPFlag("top-k", rootCmd.PersistentFlags().Lookup("top-k"))
 	_ = viper.BindPFlag("stop-sequences", rootCmd.PersistentFlags().Lookup("stop-sequences"))
+	_ = viper.BindPFlag("thinking-level", rootCmd.PersistentFlags().Lookup("thinking-level"))
 	_ = viper.BindPFlag("num-gpu-layers", rootCmd.PersistentFlags().Lookup("num-gpu-layers"))
 	_ = viper.BindPFlag("main-gpu", rootCmd.PersistentFlags().Lookup("main-gpu"))
 	_ = viper.BindPFlag("tls-skip-verify", rootCmd.PersistentFlags().Lookup("tls-skip-verify"))
@@ -277,6 +284,62 @@ func init() {
 	rootCmd.AddCommand(authCmd)
 }
 
+// processPositionalArgs separates positional CLI arguments into @file
+// attachments and prompt text. File content is read and prepended to
+// positionalPrompt so the agent receives it. Positional args are the primary
+// way to run non-interactive mode:
+//
+//	kit "Explain this codebase"
+//	kit @code.ts @test.ts "Review these files"
+func processPositionalArgs(args []string) {
+	cwd, err := os.Getwd()
+	if err != nil {
+		cwd = "."
+	}
+
+	var fileTokens []string
+	var promptParts []string
+
+	for _, arg := range args {
+		if strings.HasPrefix(arg, "@") && len(arg) > 1 {
+			fileTokens = append(fileTokens, arg)
+		} else {
+			promptParts = append(promptParts, arg)
+		}
+	}
+
+	// Build file content prefix from @file arguments.
+	var fileContent strings.Builder
+	for _, token := range fileTokens {
+		expanded := ui.ProcessFileAttachments(token, cwd)
+		if expanded != token {
+			// File was resolved — add it.
+			fileContent.WriteString(expanded)
+			fileContent.WriteString("\n\n")
+		}
+	}
+
+	// Combine: positional prompt text is appended to any existing --prompt
+	// value (for backward compat with subprocess invocations).
+	if len(promptParts) > 0 {
+		extra := strings.Join(promptParts, " ")
+		if positionalPrompt != "" {
+			positionalPrompt = positionalPrompt + " " + extra
+		} else {
+			positionalPrompt = extra
+		}
+	}
+
+	// Prepend file content to the prompt.
+	if fileContent.Len() > 0 {
+		if positionalPrompt == "" {
+			positionalPrompt = strings.TrimSpace(fileContent.String())
+		} else {
+			positionalPrompt = strings.TrimSpace(fileContent.String()) + "\n\n" + positionalPrompt
+		}
+	}
+}
+
 func runKit(ctx context.Context) error {
 	return runNormalMode(ctx)
 }
@@ -521,17 +584,17 @@ func globalShortcutsProviderForUI(k *kit.Kit) func() map[string]func() {
 
 func runNormalMode(ctx context.Context) error {
 	// Validate flag combinations
-	if quietFlag && promptFlag == "" {
-		return fmt.Errorf("--quiet flag can only be used with --prompt/-p")
+	if quietFlag && positionalPrompt == "" {
+		return fmt.Errorf("--quiet requires a prompt (e.g. kit \"your question\" --quiet)")
 	}
-	if jsonFlag && promptFlag == "" {
-		return fmt.Errorf("--json flag can only be used with --prompt/-p")
+	if jsonFlag && positionalPrompt == "" {
+		return fmt.Errorf("--json requires a prompt (e.g. kit \"your question\" --json)")
 	}
 	if jsonFlag && noExitFlag {
 		return fmt.Errorf("--json and --no-exit flags cannot be used together")
 	}
-	if noExitFlag && promptFlag == "" {
-		return fmt.Errorf("--no-exit flag can only be used with --prompt/-p")
+	if noExitFlag && positionalPrompt == "" {
+		return fmt.Errorf("--no-exit requires a prompt (e.g. kit \"your question\" --no-exit)")
 	}
 
 	// Set up logging
@@ -598,7 +661,7 @@ func runNormalMode(ctx context.Context) error {
 
 	// Create CLI for non-interactive mode only.
 	var cli *ui.CLI
-	if promptFlag != "" {
+	if positionalPrompt != "" {
 		cli, err = SetupCLIForNonInteractive(kitInstance)
 		if err != nil {
 			return fmt.Errorf("failed to setup CLI: %v", err)
@@ -645,7 +708,7 @@ func runNormalMode(ctx context.Context) error {
 		kitInstance.SetExtensionContext(extensions.Context{
 			CWD:           cwd,
 			Model:         modelName,
-			Interactive:   promptFlag == "",
+			Interactive:   positionalPrompt == "",
 			Print:         func(text string) { appInstance.PrintFromExtension("", text) },
 			PrintInfo:     func(text string) { appInstance.PrintFromExtension("info", text) },
 			PrintError:    func(text string) { appInstance.PrintFromExtension("error", text) },
@@ -861,6 +924,32 @@ func runNormalMode(ctx context.Context) error {
 					Index:  resp.Index,
 				}
 			},
+			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
+				// In-process subagent via SDK.
+				result, err := kitInstance.Subagent(ctx, kit.SubagentConfig{
+					Prompt:       config.Prompt,
+					Model:        config.Model,
+					SystemPrompt: config.SystemPrompt,
+					Timeout:      config.Timeout,
+					NoSession:    config.NoSession,
+				})
+				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()
 	}
@@ -902,17 +991,40 @@ func runNormalMode(ctx context.Context) error {
 		return extensionCommandsForUI(kitInstance)
 	}
 
+	// Build model switching callbacks for the /model command.
+	setModelForUI := func(modelString string) error {
+		err := kitInstance.SetModel(context.Background(), modelString)
+		if err != nil {
+			return err
+		}
+		// Update the extension context's Model field so handlers see it.
+		kitInstance.UpdateExtensionContextModel(modelString)
+		// NOTE: We do NOT call appInstance.NotifyModelChanged() here because
+		// this callback runs synchronously inside BubbleTea's Update(), and
+		// NotifyModelChanged calls prog.Send() which deadlocks. The UI layer
+		// updates m.providerName and m.modelName directly after setModel returns.
+		return nil
+	}
+	emitModelChangeForUI := func(newModel, previousModel, source string) {
+		kitInstance.EmitModelChange(newModel, previousModel, source)
+	}
+
+	// Build thinking level callback.
+	setThinkingLevelForUI := func(level string) error {
+		return kitInstance.SetThinkingLevel(context.Background(), level)
+	}
+
 	// Check if running in non-interactive mode
-	if promptFlag != "" {
-		return runNonInteractiveModeApp(ctx, appInstance, cli, promptFlag, quietFlag, jsonFlag, noExitFlag, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands)
+	if positionalPrompt != "" {
+		return runNonInteractiveModeApp(ctx, appInstance, cli, positionalPrompt, quietFlag, jsonFlag, noExitFlag, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModelForUI, emitModelChangeForUI, kitInstance.IsReasoningModel(), kitInstance.GetThinkingLevel(), setThinkingLevelForUI)
 	}
 
 	// Quiet mode is not allowed in interactive mode
 	if quietFlag {
-		return fmt.Errorf("--quiet flag can only be used with --prompt/-p")
+		return fmt.Errorf("--quiet requires a prompt")
 	}
 
-	return runInteractiveModeBubbleTea(ctx, appInstance, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands)
+	return runInteractiveModeBubbleTea(ctx, appInstance, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModelForUI, emitModelChangeForUI, kitInstance.IsReasoningModel(), kitInstance.GetThinkingLevel(), setThinkingLevelForUI)
 }
 
 // runNonInteractiveModeApp executes a single prompt via the app layer and exits,
@@ -925,7 +1037,12 @@ func runNormalMode(ctx context.Context) error {
 //
 // When --no-exit is set, after the prompt completes the interactive BubbleTea
 // TUI is started so the user can continue the conversation.
-func runNonInteractiveModeApp(ctx context.Context, appInstance *app.App, cli *ui.CLI, prompt string, quiet, jsonOutput, noExit bool, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []ui.ExtensionCommand, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []ui.ExtensionCommand) error {
+func runNonInteractiveModeApp(ctx context.Context, appInstance *app.App, cli *ui.CLI, prompt string, quiet, jsonOutput, noExit bool, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []ui.ExtensionCommand, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []ui.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error) error {
+	// Expand @file references in the prompt before sending to the agent.
+	if cwd, err := os.Getwd(); err == nil {
+		prompt = ui.ProcessFileAttachments(prompt, cwd)
+	}
+
 	if jsonOutput {
 		// JSON mode: no intermediate display, structured JSON output.
 		result, err := appInstance.RunOnceResult(ctx, prompt)
@@ -963,7 +1080,7 @@ func runNonInteractiveModeApp(ctx context.Context, appInstance *app.App, cli *ui
 
 	// If --no-exit was requested, hand off to the interactive TUI.
 	if noExit {
-		return runInteractiveModeBubbleTea(ctx, appInstance, modelName, providerName, loadingMessage, serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands)
+		return runInteractiveModeBubbleTea(ctx, appInstance, modelName, providerName, loadingMessage, serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModel, emitModelChange, isReasoningModel, thinkingLevel, setThinkingLevel)
 	}
 
 	return nil
@@ -992,15 +1109,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 {
@@ -1057,7 +1178,7 @@ func writeJSONError(err error) {
 //  4. Calls program.Run() which blocks until the user quits (Ctrl+C or /quit).
 //
 // SetupCLI is not used for interactive mode; the TUI (AppModel) handles its own rendering.
-func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []ui.ExtensionCommand, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []ui.ExtensionCommand) error {
+func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []ui.ExtensionCommand, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []ui.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error) error {
 	// Determine terminal size; fall back gracefully.
 	termWidth, termHeight, err := term.GetSize(int(os.Stdout.Fd()))
 	if err != nil || termWidth == 0 {
@@ -1065,11 +1186,13 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 		termHeight = 24
 	}
 
+	cwd, _ := os.Getwd()
 	appModel := ui.NewAppModel(appInstance, ui.AppModelOptions{
 		CompactMode:             viper.GetBool("compact"),
 		ModelName:               modelName,
 		ProviderName:            providerName,
 		LoadingMessage:          loadingMessage,
+		Cwd:                     cwd,
 		Width:                   termWidth,
 		Height:                  termHeight,
 		ServerNames:             serverNames,
@@ -1091,6 +1214,11 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 		EmitBeforeSessionSwitch: emitBeforeSessionSwitch,
 		GetGlobalShortcuts:      getGlobalShortcuts,
 		GetExtensionCommands:    getExtensionCommands,
+		SetModel:                setModel,
+		EmitModelChange:         emitModelChange,
+		ThinkingLevel:           thinkingLevel,
+		IsReasoningModel:        isReasoningModel,
+		SetThinkingLevel:        setThinkingLevel,
 	})
 
 	// Print startup info to stdout before Bubble Tea takes over the screen.

cmd/skill.go

@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+
+	"github.com/spf13/cobra"
+)
+
+// skillCmd installs the kit-extensions skill via the skills.sh CLI (npx skills).
+// This teaches AI agents how to create Kit extensions with full knowledge of
+// the extension API, lifecycle events, widgets, tools, commands, and Yaegi constraints.
+var skillCmd = &cobra.Command{
+	Use:   "skill",
+	Short: "Install the Kit extensions skill via skills.sh",
+	Long: `Install the kit-extensions skill that teaches AI agents how to create
+Kit extensions. Uses the skills.sh CLI (npx skills) to install the skill
+from the Kit repository.
+
+The skill provides comprehensive documentation of Kit's extension API including
+lifecycle events, custom tools, slash commands, widgets, editor interceptors,
+tool renderers, and critical Yaegi interpreter constraints.
+
+Example:
+  kit skill`,
+	RunE: runSkill,
+}
+
+func init() {
+	rootCmd.AddCommand(skillCmd)
+}
+
+func runSkill(_ *cobra.Command, _ []string) error {
+	npx, err := exec.LookPath("npx")
+	if err != nil {
+		return fmt.Errorf("npx not found in PATH — install Node.js to use this command: %w", err)
+	}
+
+	args := []string{
+		"skills",
+		"add",
+		"mark3labs/kit",
+		"--skill",
+		"kit-extensions",
+	}
+
+	cmd := exec.Command(npx, args...)
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("skills install failed: %w", err)
+	}
+
+	return nil
+}

examples/extensions/kit-kit.go

@@ -488,11 +488,11 @@ func queryExpert(name, question string) (output string, exitCode int, elapsed ti
 	// Build subprocess arguments. Use --json for structured output parsing.
 	// Don't pass --model; the subprocess inherits the same config/env default.
 	args := []string{
-		"--prompt", question,
 		"--json",
 		"--no-session",
 		"--no-extensions",
 		"--system-prompt", tmpFile.Name(),
+		question,
 	}
 
 	var stdoutBuf, stderrBuf bytes.Buffer

examples/extensions/subagent-test.go

@@ -0,0 +1,164 @@
+//go:build ignore
+
+// Subagent Test Extension — Tests the new first-class subagent API
+//
+// Commands:
+//
+//	/subtest <task>      — spawn a blocking subagent and print result
+//	/subbg <task>        — spawn a background subagent with live output
+//
+// Usage: kit -e examples/extensions/subagent-test.go
+package main
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"kit/ext"
+)
+
+var (
+	mu        sync.Mutex
+	latestCtx ext.Context
+	hasCtx    bool
+)
+
+func Init(api ext.API) {
+	// Keep context fresh
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		mu.Lock()
+		latestCtx = ctx
+		hasCtx = true
+		mu.Unlock()
+
+		ctx.PrintInfo(
+			"Subagent Test Extension loaded\n\n" +
+				"/subtest <task>    Spawn blocking subagent\n" +
+				"/subbg <task>      Spawn background subagent\n\n" +
+				"The LLM can also use the spawn_subagent tool.")
+	})
+
+	api.OnAgentEnd(func(_ ext.AgentEndEvent, ctx ext.Context) {
+		mu.Lock()
+		latestCtx = ctx
+		mu.Unlock()
+	})
+
+	// Command: /subtest <task> — blocking subagent
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "subtest",
+		Description: "Spawn a blocking subagent: /subtest <task>",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			hasCtx = true
+			mu.Unlock()
+
+			task := strings.TrimSpace(args)
+			if task == "" {
+				return "Usage: /subtest <task>", nil
+			}
+
+			ctx.PrintInfo(fmt.Sprintf("Spawning blocking subagent for: %s", task))
+
+			start := time.Now()
+			_, result, err := ctx.SpawnSubagent(ext.SubagentConfig{
+				Prompt:   task,
+				Timeout:  2 * time.Minute,
+				Blocking: true,
+			})
+			elapsed := time.Since(start)
+
+			if err != nil {
+				return fmt.Sprintf("Spawn error: %v", err), nil
+			}
+
+			if result == nil {
+				return "No result returned", nil
+			}
+
+			if result.Error != nil {
+				return fmt.Sprintf("Subagent failed (exit %d) after %ds: %v\n\nPartial output:\n%s",
+					result.ExitCode, int(elapsed.Seconds()), result.Error, truncate(result.Response, 2000)), nil
+			}
+
+			response := fmt.Sprintf("Subagent completed in %ds", int(elapsed.Seconds()))
+			if result.Usage != nil {
+				response += fmt.Sprintf(" (tokens: %d in / %d out)", result.Usage.InputTokens, result.Usage.OutputTokens)
+			}
+			response += fmt.Sprintf("\n\nResult:\n%s", truncate(result.Response, 4000))
+
+			return response, nil
+		},
+	})
+
+	// Command: /subbg <task> — background subagent with callbacks
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "subbg",
+		Description: "Spawn a background subagent: /subbg <task>",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			hasCtx = true
+			mu.Unlock()
+
+			task := strings.TrimSpace(args)
+			if task == "" {
+				return "Usage: /subbg <task>", nil
+			}
+
+			ctx.PrintInfo(fmt.Sprintf("Spawning background subagent for: %s", task))
+
+			start := time.Now()
+			handle, _, err := ctx.SpawnSubagent(ext.SubagentConfig{
+				Prompt:  task,
+				Timeout: 2 * time.Minute,
+				OnOutput: func(chunk string) {
+					// Live output - could update a widget here
+					fmt.Print(chunk)
+				},
+				OnComplete: func(result ext.SubagentResult) {
+					elapsed := time.Since(start)
+
+					mu.Lock()
+					c := latestCtx
+					ok := hasCtx
+					mu.Unlock()
+
+					if !ok {
+						return
+					}
+
+					if result.Error != nil {
+						c.SendMessage(fmt.Sprintf("Background subagent failed after %ds: %v",
+							int(elapsed.Seconds()), result.Error))
+						return
+					}
+
+					msg := fmt.Sprintf("Background subagent completed in %ds", int(elapsed.Seconds()))
+					if result.Usage != nil {
+						msg += fmt.Sprintf(" (tokens: %d in / %d out)", result.Usage.InputTokens, result.Usage.OutputTokens)
+					}
+					msg += fmt.Sprintf("\n\nResult:\n%s", truncate(result.Response, 4000))
+
+					c.SendMessage(msg)
+				},
+			})
+
+			if err != nil {
+				return fmt.Sprintf("Spawn error: %v", err), nil
+			}
+
+			return fmt.Sprintf("Background subagent spawned (ID: %s). Results will be delivered when complete.", handle.ID), nil
+		},
+	})
+}
+
+func truncate(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max] + "\n\n... [truncated]"
+}

examples/extensions/subagent-widget.go

@@ -209,10 +209,10 @@ func spawnAgent(state *subState) {
 	}
 
 	args := []string{
-		"--prompt", prompt,
 		"--json",
 		"--no-session",
 		"--no-extensions",
+		prompt,
 	}
 
 	cmd := exec.Command(kitBinary, args...)

go.mod

@@ -4,13 +4,17 @@ go 1.26.0
 
 require (
 	charm.land/bubbles/v2 v2.0.0
-	charm.land/bubbletea/v2 v2.0.0
-	charm.land/fantasy v0.10.0
+	charm.land/bubbletea/v2 v2.0.1
+	charm.land/fantasy v0.11.1
 	charm.land/lipgloss/v2 v2.0.0
+	github.com/alecthomas/chroma/v2 v2.23.1
+	github.com/aymanbagabas/go-udiff v0.4.0
 	github.com/charmbracelet/fang v0.4.4
-	github.com/mark3labs/mcp-go v0.44.0
+	github.com/charmbracelet/log v0.4.2
+	github.com/mark3labs/mcp-go v0.44.1
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
+	github.com/traefik/yaegi v0.16.1
 	golang.org/x/term v0.40.0
 	gopkg.in/yaml.v3 v3.0.1
 )
@@ -22,24 +26,22 @@ require (
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect
-	github.com/alecthomas/chroma/v2 v2.23.1 // indirect
 	github.com/atotto/clipboard v0.1.4 // indirect
-	github.com/aws/aws-sdk-go-v2 v1.41.2 // indirect
-	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.5 // indirect
-	github.com/aws/aws-sdk-go-v2/config v1.32.10 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.10 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.18 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.18 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.18 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.5 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.18 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.0.6 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.11 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.15 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.41.7 // indirect
-	github.com/aws/smithy-go v1.24.1 // indirect
-	github.com/aymanbagabas/go-udiff v0.4.0 // indirect
+	github.com/aws/aws-sdk-go-v2 v1.41.3 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.6 // indirect
+	github.com/aws/aws-sdk-go-v2/config v1.32.11 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.11 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.19 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.19 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.19 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.5 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.6 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.19 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.0.7 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.12 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.16 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.41.8 // indirect
+	github.com/aws/smithy-go v1.24.2 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/buger/jsonparser v1.1.1 // indirect
@@ -48,21 +50,21 @@ require (
 	github.com/charmbracelet/colorprofile v0.4.2 // indirect
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 // indirect
-	github.com/charmbracelet/log v0.4.2 // indirect
-	github.com/charmbracelet/ultraviolet v0.0.0-20260223171050-89c142e4aa73 // indirect
+	github.com/charmbracelet/ultraviolet v0.0.0-20260303162955-0b88c25f3fff // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
-	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260223200540-d6a276319c45 // indirect
-	github.com/charmbracelet/x/exp/slice v0.0.0-20260223200540-d6a276319c45 // indirect
+	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260305213658-fe36e8c10185 // indirect
+	github.com/charmbracelet/x/exp/slice v0.0.0-20260305213658-fe36e8c10185 // indirect
 	github.com/charmbracelet/x/json v0.2.0 // indirect
 	github.com/charmbracelet/x/termios v0.1.1 // indirect
 	github.com/charmbracelet/x/windows v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
+	github.com/coder/acp-go-sdk v0.6.3 // indirect
 	github.com/dlclark/regexp2 v1.11.5 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 // indirect
-	github.com/go-logfmt/logfmt v0.6.0 // indirect
+	github.com/go-logfmt/logfmt v0.6.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
@@ -71,14 +73,14 @@ require (
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/googleapis/enterprise-certificate-proxy v0.3.12 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.14 // indirect
 	github.com/googleapis/gax-go/v2 v2.17.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/gorilla/websocket v1.5.3 // indirect
 	github.com/invopop/jsonschema v0.13.0 // indirect
-	github.com/kaptinlin/go-i18n v0.2.11 // indirect
-	github.com/kaptinlin/jsonpointer v0.4.16 // indirect
-	github.com/kaptinlin/jsonschema v0.7.3 // indirect
+	github.com/kaptinlin/go-i18n v0.2.12 // indirect
+	github.com/kaptinlin/jsonpointer v0.4.17 // indirect
+	github.com/kaptinlin/jsonschema v0.7.5 // indirect
 	github.com/kaptinlin/messageformat-go v0.4.18 // indirect
 	github.com/mailru/easyjson v0.9.1 // indirect
 	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
@@ -97,28 +99,27 @@ require (
 	github.com/tidwall/match v1.2.0 // indirect
 	github.com/tidwall/pretty v1.2.1 // indirect
 	github.com/tidwall/sjson v1.2.5 // indirect
-	github.com/traefik/yaegi v0.16.1 // indirect
 	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/yuin/goldmark v1.7.16 // indirect
 	github.com/yuin/goldmark-emoji v1.0.6 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.65.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
-	go.opentelemetry.io/otel v1.40.0 // indirect
-	go.opentelemetry.io/otel/metric v1.40.0 // indirect
-	go.opentelemetry.io/otel/trace v1.40.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.66.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.66.0 // indirect
+	go.opentelemetry.io/otel v1.41.0 // indirect
+	go.opentelemetry.io/otel/metric v1.41.0 // indirect
+	go.opentelemetry.io/otel/trace v1.41.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
 	golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa // indirect
-	golang.org/x/net v0.50.0 // indirect
+	golang.org/x/net v0.51.0 // indirect
 	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	google.golang.org/api v0.269.0 // indirect
-	google.golang.org/genai v1.47.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260223185530-2f722ef697dc // indirect
-	google.golang.org/grpc v1.79.1 // indirect
+	google.golang.org/genai v1.49.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 // indirect
+	google.golang.org/grpc v1.79.2 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )

go.sum

@@ -1,9 +1,9 @@
 charm.land/bubbles/v2 v2.0.0 h1:tE3eK/pHjmtrDiRdoC9uGNLgpopOd8fjhEe31B/ai5s=
 charm.land/bubbles/v2 v2.0.0/go.mod h1:rCHoleP2XhU8um45NTuOWBPNVHxnkXKTiZqcclL/qOI=
-charm.land/bubbletea/v2 v2.0.0 h1:p0d6CtWyJXJ9GfzMpUUqbP/XUUhhlk06+vCKWmox1wQ=
-charm.land/bubbletea/v2 v2.0.0/go.mod h1:3LRff2U4WIYXy7MTxfbAQ+AdfM3D8Xuvz2wbsOD9OHQ=
-charm.land/fantasy v0.10.0 h1:6PD+1rrsCgLIG1n+PAZp/gHiC0dltU0cvb7c8zUKyu8=
-charm.land/fantasy v0.10.0/go.mod h1:KIeNQUpJTswwpY0P6HJsr3LBFgfTDb8FDpOdVQMsKqY=
+charm.land/bubbletea/v2 v2.0.1 h1:B8e9zzK7x9JJ+XvHGF4xnYu9Xa0E0y0MyggY6dbaCfQ=
+charm.land/bubbletea/v2 v2.0.1/go.mod h1:3LRff2U4WIYXy7MTxfbAQ+AdfM3D8Xuvz2wbsOD9OHQ=
+charm.land/fantasy v0.11.1 h1:G1dRqkzEQ0RJN1Ls5mte8HOi0wFKxYd5bfnRAmeYvDk=
+charm.land/fantasy v0.11.1/go.mod h1:C8wNxWlw+b2z54zsTor9r1tG2GE2C4QotvAlgXh9KF8=
 charm.land/lipgloss/v2 v2.0.0 h1:sd8N/B3x892oiOjFfBQdXBQp3cAkvjGaU5TvVZC3ivo=
 charm.land/lipgloss/v2 v2.0.0/go.mod h1:w6SnmsBFBmEFBodiEDurGS/sdUY/u1+v72DqUzc6J14=
 cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE=
@@ -32,36 +32,36 @@ github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs
 github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
 github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
-github.com/aws/aws-sdk-go-v2 v1.41.2 h1:LuT2rzqNQsauaGkPK/7813XxcZ3o3yePY0Iy891T2ls=
-github.com/aws/aws-sdk-go-v2 v1.41.2/go.mod h1:IvvlAZQXvTXznUPfRVfryiG1fbzE2NGK6m9u39YQ+S4=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.5 h1:zWFmPmgw4sveAYi1mRqG+E/g0461cJ5M4bJ8/nc6d3Q=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.5/go.mod h1:nVUlMLVV8ycXSb7mSkcNu9e3v/1TJq2RTlrPwhYWr5c=
-github.com/aws/aws-sdk-go-v2/config v1.32.10 h1:9DMthfO6XWZYLfzZglAgW5Fyou2nRI5CuV44sTedKBI=
-github.com/aws/aws-sdk-go-v2/config v1.32.10/go.mod h1:2rUIOnA2JaiqYmSKYmRJlcMWy6qTj1vuRFscppSBMcw=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.10 h1:EEhmEUFCE1Yhl7vDhNOI5OCL/iKMdkkYFTRpZXNw7m8=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.10/go.mod h1:RnnlFCAlxQCkN2Q379B67USkBMu1PipEEiibzYN5UTE=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.18 h1:Ii4s+Sq3yDfaMLpjrJsqD6SmG/Wq/P5L/hw2qa78UAY=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.18/go.mod h1:6x81qnY++ovptLE6nWQeWrpXxbnlIex+4H4eYYGcqfc=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.18 h1:F43zk1vemYIqPAwhjTjYIz0irU2EY7sOb/F5eJ3HuyM=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.18/go.mod h1:w1jdlZXrGKaJcNoL+Nnrj+k5wlpGXqnNrKoP22HvAug=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.18 h1:xCeWVjj0ki0l3nruoyP2slHsGArMxeiiaoPN5QZH6YQ=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.18/go.mod h1:r/eLGuGCBw6l36ZRWiw6PaZwPXb6YOj+i/7MizNl5/k=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 h1:WKuaxf++XKWlHWu9ECbMlha8WOEGm0OUEZqm4K/Gcfk=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4/go.mod h1:ZWy7j6v1vWGmPReu0iSGvRiise4YI5SkR3OHKTZ6Wuc=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.5 h1:CeY9LUdur+Dxoeldqoun6y4WtJ3RQtzk0JMP2gfUay0=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.5/go.mod h1:AZLZf2fMaahW5s/wMRciu1sYbdsikT/UHwbUjOdEVTc=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.18 h1:LTRCYFlnnKFlKsyIQxKhJuDuA3ZkrDQMRYm6rXiHlLY=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.18/go.mod h1:XhwkgGG6bHSd00nO/mexWTcTjgd6PjuvWQMqSn2UaEk=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.6 h1:MzORe+J94I+hYu2a6XmV5yC9huoTv8NRcCrUNedDypQ=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.6/go.mod h1:hXzcHLARD7GeWnifd8j9RWqtfIgxj4/cAtIVIK7hg8g=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.11 h1:7oGD8KPfBOJGXiCoRKrrrQkbvCp8N++u36hrLMPey6o=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.11/go.mod h1:0DO9B5EUJQlIDif+XJRWCljZRKsAFKh3gpFz7UnDtOo=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.15 h1:edCcNp9eGIUDUCrzoCu1jWAXLGFIizeqkdkKgRlJwWc=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.15/go.mod h1:lyRQKED9xWfgkYC/wmmYfv7iVIM68Z5OQ88ZdcV1QbU=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.7 h1:NITQpgo9A5NrDZ57uOWj+abvXSb83BbyggcUBVksN7c=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.7/go.mod h1:sks5UWBhEuWYDPdwlnRFn1w7xWdH29Jcpe+/PJQefEs=
-github.com/aws/smithy-go v1.24.1 h1:VbyeNfmYkWoxMVpGUAbQumkODcYmfMRfZ8yQiH30SK0=
-github.com/aws/smithy-go v1.24.1/go.mod h1:LEj2LM3rBRQJxPZTB4KuzZkaZYnZPnvgIhb4pu07mx0=
+github.com/aws/aws-sdk-go-v2 v1.41.3 h1:4kQ/fa22KjDt13QCy1+bYADvdgcxpfH18f0zP542kZA=
+github.com/aws/aws-sdk-go-v2 v1.41.3/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.6 h1:N4lRUXZpZ1KVEUn6hxtco/1d2lgYhNn1fHkkl8WhlyQ=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.6/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
+github.com/aws/aws-sdk-go-v2/config v1.32.11 h1:ftxI5sgz8jZkckuUHXfC/wMUc8u3fG1vQS0plr2F2Zs=
+github.com/aws/aws-sdk-go-v2/config v1.32.11/go.mod h1:twF11+6ps9aNRKEDimksp923o44w/Thk9+8YIlzWMmo=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.11 h1:NdV8cwCcAXrCWyxArt58BrvZJ9pZ9Fhf9w6Uh5W3Uyc=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.11/go.mod h1:30yY2zqkMPdrvxBqzI9xQCM+WrlrZKSOpSJEsylVU+8=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.19 h1:INUvJxmhdEbVulJYHI061k4TVuS3jzzthNvjqvVvTKM=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.19/go.mod h1:FpZN2QISLdEBWkayloda+sZjVJL+e9Gl0k1SyTgcswU=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.19 h1:/sECfyq2JTifMI2JPyZ4bdRN77zJmr6SrS1eL3augIA=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.19/go.mod h1:dMf8A5oAqr9/oxOfLkC/c2LU/uMcALP0Rgn2BD5LWn0=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.19 h1:AWeJMk33GTBf6J20XJe6qZoRSJo0WfUhsMdUKhoODXE=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.19/go.mod h1:+GWrYoaAsV7/4pNHpwh1kiNLXkKaSoppxQq9lbH8Ejw=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.5 h1:clHU5fm//kWS1C2HgtgWxfQbFbx4b6rx+5jzhgX9HrI=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.5/go.mod h1:O3h0IK87yXci+kg6flUKzJnWeziQUKciKrLjcatSNcY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.6 h1:XAq62tBTJP/85lFD5oqOOe7YYgWxY9LvWq8plyDvDVg=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.6/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.19 h1:X1Tow7suZk9UCJHE1Iw9GMZJJl0dAnKXXP1NaSDHwmw=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.19/go.mod h1:/rARO8psX+4sfjUQXp5LLifjUt8DuATZ31WptNJTyQA=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.7 h1:Y2cAXlClHsXkkOvWZFXATr34b0hxxloeQu/pAZz2row=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.7/go.mod h1:idzZ7gmDeqeNrSPkdbtMp9qWMgcBwykA7P7Rzh5DXVU=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.12 h1:iSsvB9EtQ09YrsmIc44Heqlx5ByGErqhPK1ZQLppias=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.12/go.mod h1:fEWYKTRGoZNl8tZ77i61/ccwOMJdGxwOhWCkp6TXAr0=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.16 h1:EnUdUqRP1CNzt2DkV67tJx6XDN4xlfBFm+bzeNOQVb0=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.16/go.mod h1:Jic/xv0Rq/pFNCh3WwpH4BEqdbSAl+IyHro8LbibHD8=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.8 h1:XQTQTF75vnug2TXS8m7CVJfC2nniYPZnO1D4Np761Oo=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.8/go.mod h1:Xgx+PR1NUOjNmQY+tRMnouRp83JRM8pRMw/vCaVhPkI=
+github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
+github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
 github.com/aymanbagabas/go-udiff v0.4.0 h1:TKnLPh7IbnizJIBKFWa9mKayRUBQ9Kh1BPCk6w2PnYM=
@@ -88,18 +88,18 @@ github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 h1:ZR7e0r
 github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834/go.mod h1:aKC/t2arECF6rNOnaKaVU6y4t4ZeHQzqfxedE/VkVhA=
 github.com/charmbracelet/log v0.4.2 h1:hYt8Qj6a8yLnvR+h7MwsJv/XvmBJXiueUcI3cIxsyig=
 github.com/charmbracelet/log v0.4.2/go.mod h1:qifHGX/tc7eluv2R6pWIpyHDDrrb/AG71Pf2ysQu5nw=
-github.com/charmbracelet/ultraviolet v0.0.0-20260223171050-89c142e4aa73 h1:Af/L28Xh+pddhouT/6lJ7IAIYfu5tWJOB0iqt+mXsYM=
-github.com/charmbracelet/ultraviolet v0.0.0-20260223171050-89c142e4aa73/go.mod h1:E6/0abq9uG2SnM8IbLB9Y5SW09uIgfaFETk8aRzgXUQ=
+github.com/charmbracelet/ultraviolet v0.0.0-20260303162955-0b88c25f3fff h1:uY7A6hTokHPJBHfq7rj9Y/wm+IAjOghZTxKfVW6QLvw=
+github.com/charmbracelet/ultraviolet v0.0.0-20260303162955-0b88c25f3fff/go.mod h1:E6/0abq9uG2SnM8IbLB9Y5SW09uIgfaFETk8aRzgXUQ=
 github.com/charmbracelet/x/ansi v0.11.6 h1:GhV21SiDz/45W9AnV2R61xZMRri5NlLnl6CVF7ihZW8=
 github.com/charmbracelet/x/ansi v0.11.6/go.mod h1:2JNYLgQUsyqaiLovhU2Rv/pb8r6ydXKS3NIttu3VGZQ=
 github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
 github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260223200540-d6a276319c45 h1:t/EWU3ZOrVxmr2d19f+1wnWr92p1O82oOTm7ASxodsA=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260223200540-d6a276319c45/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260305213658-fe36e8c10185 h1:/192monmpmRICpSPrFRzkIO+xfhioV6/nwrQdkDTj10=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260305213658-fe36e8c10185/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f h1:pk6gmGpCE7F3FcjaOEKYriCvpmIN4+6OS/RD0vm4uIA=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f/go.mod h1:IfZAMTHB6XkZSeXUqriemErjAWCCzT0LwjKFYCZyw0I=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260223200540-d6a276319c45 h1:jgQlAnMmwbjtvd91AzjWWFtwpIZ2P/Nspx5zyrhmPec=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260223200540-d6a276319c45/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260305213658-fe36e8c10185 h1:bloHJLweYZeIkBVgi8AF94DrTdx3eoEB57VOpFuFi3U=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260305213658-fe36e8c10185/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
 github.com/charmbracelet/x/json v0.2.0 h1:DqB+ZGx2h+Z+1s98HOuOyli+i97wsFQIxP2ZQANTPrQ=
 github.com/charmbracelet/x/json v0.2.0/go.mod h1:opFIflx2YgXgi49xVUu8gEQ21teFAxyMwvOiZhIvWNM=
 github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
@@ -114,6 +114,8 @@ github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJ
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os8IaYg++6uMOdKK83QtkkvJik=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=
+github.com/coder/acp-go-sdk v0.6.3 h1:LsXQytehdjKIYJnoVWON/nf7mqbiarnyuyE3rrjBsXQ=
+github.com/coder/acp-go-sdk v0.6.3/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -134,8 +136,8 @@ github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
 github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
-github.com/go-logfmt/logfmt v0.6.0 h1:wGYYu3uicYdqXVgoYbvnkrPVXkuLM1p1ifugDMEdRi4=
-github.com/go-logfmt/logfmt v0.6.0/go.mod h1:WYhtIu8zTZfxdn5+rREduYbwxfcBr/Vr6KEVveWlfTs=
+github.com/go-logfmt/logfmt v0.6.1 h1:4hvbpePJKnIzH1B+8OR/JPbTx37NktoI9LE2QZBBkvE=
+github.com/go-logfmt/logfmt v0.6.1/go.mod h1:EV2pOAQoZaT1ZXZbqDl5hrymndi4SY9ED9/z6CO0XAk=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
@@ -155,8 +157,8 @@ github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
 github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-github.com/googleapis/enterprise-certificate-proxy v0.3.12 h1:Fg+zsqzYEs1ZnvmcztTYxhgCBsx3eEhEwQ1W/lHq/sQ=
-github.com/googleapis/enterprise-certificate-proxy v0.3.12/go.mod h1:vqVt9yG9480NtzREnTlmGSBmFrA+bzb0yl0TxoBQXOg=
+github.com/googleapis/enterprise-certificate-proxy v0.3.14 h1:yh8ncqsbUY4shRD5dA6RlzjJaT4hi3kII+zYw8wmLb8=
+github.com/googleapis/enterprise-certificate-proxy v0.3.14/go.mod h1:vqVt9yG9480NtzREnTlmGSBmFrA+bzb0yl0TxoBQXOg=
 github.com/googleapis/gax-go/v2 v2.17.0 h1:RksgfBpxqff0EZkDWYuz9q/uWsTVz+kf43LsZ1J6SMc=
 github.com/googleapis/gax-go/v2 v2.17.0/go.mod h1:mzaqghpQp4JDh3HvADwrat+6M3MOIDp5YKHhb9PAgDY=
 github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
@@ -169,12 +171,12 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
 github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
-github.com/kaptinlin/go-i18n v0.2.11 h1:OayNt8mWt8nDaqAOp09/C1VG9Y5u8LpQnnxbyGARDV4=
-github.com/kaptinlin/go-i18n v0.2.11/go.mod h1:pVcu9qsW5pOIOoZFJXesRYmLos1vMQrby70JPAoWmJU=
-github.com/kaptinlin/jsonpointer v0.4.16 h1:Ux4w4FY+uLv+K+TxaCJtM/TpPv+1+eS6gH4Z9/uhOuA=
-github.com/kaptinlin/jsonpointer v0.4.16/go.mod h1:SsfsjqnHG5zuKo1DTBzk1VknaHlL4osHw+X9kZKukpU=
-github.com/kaptinlin/jsonschema v0.7.3 h1:kyIydij76ORiSxmfy0xFYy0cOx8MwG6pyyaSoQshsK4=
-github.com/kaptinlin/jsonschema v0.7.3/go.mod h1:Ys6zr+W6/1330FzZEouFrAYImK+AmYt5HQVTHQQXQo8=
+github.com/kaptinlin/go-i18n v0.2.12 h1:ywDsvb4KDFddMC2dpI/rrIzGU2mWUSvHmWUm9BMsdl4=
+github.com/kaptinlin/go-i18n v0.2.12/go.mod h1:pVcu9qsW5pOIOoZFJXesRYmLos1vMQrby70JPAoWmJU=
+github.com/kaptinlin/jsonpointer v0.4.17 h1:mY9k8ciWncxbsECyaxKnR0MdmxamNdp2tLQkAKVrtSk=
+github.com/kaptinlin/jsonpointer v0.4.17/go.mod h1:SsfsjqnHG5zuKo1DTBzk1VknaHlL4osHw+X9kZKukpU=
+github.com/kaptinlin/jsonschema v0.7.5 h1:jkK4a3NyzNoGlvu12CsL3IcqNMVa5sL51HPVa0nWcPY=
+github.com/kaptinlin/jsonschema v0.7.5/go.mod h1:3gIWnptl+SWMyfMR2r4TXXd0xsQZ1m50AKrwmcUONSg=
 github.com/kaptinlin/messageformat-go v0.4.18 h1:RBlHVWgZyoxTcUgGWBsl2AcyScq/urqbLZvzgryTmSI=
 github.com/kaptinlin/messageformat-go v0.4.18/go.mod h1:ntI3154RnqJgr7GaC+vZBnIExl2V3sv9selvRNNEM24=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
@@ -187,8 +189,8 @@ github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQ
 github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mailru/easyjson v0.9.1 h1:LbtsOm5WAswyWbvTEOqhypdPeZzHavpZx96/n553mR8=
 github.com/mailru/easyjson v0.9.1/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU=
-github.com/mark3labs/mcp-go v0.44.0 h1:OlYfcVviAnwNN40QZUrrzU0QZjq3En7rCU5X09a/B7I=
-github.com/mark3labs/mcp-go v0.44.0/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
+github.com/mark3labs/mcp-go v0.44.1 h1:2PKppYlT9X2fXnE8SNYQLAX4hNjfPB0oNLqQVcN6mE8=
+github.com/mark3labs/mcp-go v0.44.1/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-runewidth v0.0.12/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
@@ -269,28 +271,28 @@ github.com/yuin/goldmark-emoji v1.0.6 h1:QWfF2FYaXwL74tfGOW5izeiZepUDroDJfWubQI9
 github.com/yuin/goldmark-emoji v1.0.6/go.mod h1:ukxJDKFpdFb5x0a5HqbdlcKtebh086iJpI31LTKmWuA=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.65.0 h1:XmiuHzgJt067+a6kwyAzkhXooYVv3/TOw9cM2VfJgUM=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.65.0/go.mod h1:KDgtbWKTQs4bM+VPUr6WlL9m/WXcmkCcBlIzqxPGzmI=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 h1:7iP2uCb7sGddAr30RRS6xjKy7AZ2JtTOPA3oolgVSw8=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0/go.mod h1:c7hN3ddxs/z6q9xwvfLPk+UHlWRQyaeR1LdgfL/66l0=
-go.opentelemetry.io/otel v1.40.0 h1:oA5YeOcpRTXq6NN7frwmwFR0Cn3RhTVZvXsP4duvCms=
-go.opentelemetry.io/otel v1.40.0/go.mod h1:IMb+uXZUKkMXdPddhwAHm6UfOwJyh4ct1ybIlV14J0g=
-go.opentelemetry.io/otel/metric v1.40.0 h1:rcZe317KPftE2rstWIBitCdVp89A2HqjkxR3c11+p9g=
-go.opentelemetry.io/otel/metric v1.40.0/go.mod h1:ib/crwQH7N3r5kfiBZQbwrTge743UDc7DTFVZrrXnqc=
-go.opentelemetry.io/otel/sdk v1.40.0 h1:KHW/jUzgo6wsPh9At46+h4upjtccTmuZCFAc9OJ71f8=
-go.opentelemetry.io/otel/sdk v1.40.0/go.mod h1:Ph7EFdYvxq72Y8Li9q8KebuYUr2KoeyHx0DRMKrYBUE=
-go.opentelemetry.io/otel/sdk/metric v1.40.0 h1:mtmdVqgQkeRxHgRv4qhyJduP3fYJRMX4AtAlbuWdCYw=
-go.opentelemetry.io/otel/sdk/metric v1.40.0/go.mod h1:4Z2bGMf0KSK3uRjlczMOeMhKU2rhUqdWNoKcYrtcBPg=
-go.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZYblVjw=
-go.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.66.0 h1:w/o339tDd6Qtu3+ytwt+/jon2yjAs3Ot8Xq8pelfhSo=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.66.0/go.mod h1:pdhNtM9C4H5fRdrnwO7NjxzQWhKSSxCHk/KluVqDVC0=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.66.0 h1:PnV4kVnw0zOmwwFkAzCN5O07fw1YOIQor120zrh0AVo=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.66.0/go.mod h1:ofAwF4uinaf8SXdVzzbL4OsxJ3VfeEg3f/F6CeF49/Y=
+go.opentelemetry.io/otel v1.41.0 h1:YlEwVsGAlCvczDILpUXpIpPSL/VPugt7zHThEMLce1c=
+go.opentelemetry.io/otel v1.41.0/go.mod h1:Yt4UwgEKeT05QbLwbyHXEwhnjxNO6D8L5PQP51/46dE=
+go.opentelemetry.io/otel/metric v1.41.0 h1:rFnDcs4gRzBcsO9tS8LCpgR0dxg4aaxWlJxCno7JlTQ=
+go.opentelemetry.io/otel/metric v1.41.0/go.mod h1:xPvCwd9pU0VN8tPZYzDZV/BMj9CM9vs00GuBjeKhJps=
+go.opentelemetry.io/otel/sdk v1.41.0 h1:YPIEXKmiAwkGl3Gu1huk1aYWwtpRLeskpV+wPisxBp8=
+go.opentelemetry.io/otel/sdk v1.41.0/go.mod h1:ahFdU0G5y8IxglBf0QBJXgSe7agzjE4GiTJ6HT9ud90=
+go.opentelemetry.io/otel/sdk/metric v1.41.0 h1:siZQIYBAUd1rlIWQT2uCxWJxcCO7q3TriaMlf08rXw8=
+go.opentelemetry.io/otel/sdk/metric v1.41.0/go.mod h1:HNBuSvT7ROaGtGI50ArdRLUnvRTRGniSUZbxiWxSO8Y=
+go.opentelemetry.io/otel/trace v1.41.0 h1:Vbk2co6bhj8L59ZJ6/xFTskY+tGAbOnCtQGVVa9TIN0=
+go.opentelemetry.io/otel/trace v1.41.0/go.mod h1:U1NU4ULCoxeDKc09yCWdWe+3QoyweJcISEVa1RBzOis=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
 golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
 golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa h1:Zt3DZoOFFYkKhDT3v7Lm9FDMEV06GpzjG2jrqW+QTE0=
 golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
-golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
-golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
+golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
+golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
 golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
 golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
@@ -308,12 +310,12 @@ gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
 gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
 google.golang.org/api v0.269.0 h1:qDrTOxKUQ/P0MveH6a7vZ+DNHxJQjtGm/uvdbdGXCQg=
 google.golang.org/api v0.269.0/go.mod h1:N8Wpcu23Tlccl0zSHEkcAZQKDLdquxK+l9r2LkwAauE=
-google.golang.org/genai v1.47.0 h1:iWCS7gEdO6rctOqfCYLOrZGKu2D+N42aTnCEcBvB1jo=
-google.golang.org/genai v1.47.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260223185530-2f722ef697dc h1:51Wupg8spF+5FC6D+iMKbOddFjMckETnNnEiZ+HX37s=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260223185530-2f722ef697dc/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.79.1 h1:zGhSi45ODB9/p3VAawt9a+O/MULLl9dpizzNNpq7flY=
-google.golang.org/grpc v1.79.1/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+google.golang.org/genai v1.49.0 h1:Se+QJaH2GYK1aaR1o5S38mlU2GD5FnVvP76nfkV7LH0=
+google.golang.org/genai v1.49.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 h1:ggcbiqK8WWh6l1dnltU4BgWGIGo+EVYxCaAPih/zQXQ=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.79.2 h1:fRMD94s2tITpyJGtBBn7MkMseNpOZU8ZxgC3MMBaXRU=
+google.golang.org/grpc v1.79.2/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/acpserver/agent.go

@@ -0,0 +1,260 @@
+// Package acpserver implements a Kit-backed ACP (Agent Client Protocol) agent.
+//
+// It bridges Kit's LLM execution, tool system, and session management to the
+// ACP protocol over stdio, allowing ACP clients (such as OpenCode) to drive
+// Kit as a remote coding agent.
+package acpserver
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sync/atomic"
+
+	"github.com/charmbracelet/log"
+	acp "github.com/coder/acp-go-sdk"
+
+	kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+// Version is injected at build time; fallback to "dev".
+var Version = "dev"
+
+// Agent implements the acp.Agent interface, delegating to Kit for LLM
+// execution, tool calls, and session management.
+type Agent struct {
+	conn     *acp.AgentSideConnection
+	registry *sessionRegistry
+
+	// toolCallCounter provides unique IDs for tool calls within a turn.
+	toolCallCounter atomic.Int64
+}
+
+// NewAgent creates a new ACP agent backed by Kit.
+func NewAgent() *Agent {
+	return &Agent{
+		registry: newSessionRegistry(),
+	}
+}
+
+// SetAgentConnection stores the connection so the agent can send session
+// updates (streaming, tool calls, etc.) back to the ACP client. This follows
+// the AgentConnAware duck-typing pattern from the SDK.
+func (a *Agent) SetAgentConnection(conn *acp.AgentSideConnection) {
+	a.conn = conn
+}
+
+// Close shuts down all active sessions.
+func (a *Agent) Close() {
+	a.registry.closeAll()
+}
+
+// ---------------------------------------------------------------------------
+// acp.Agent interface implementation
+// ---------------------------------------------------------------------------
+
+// Authenticate handles authentication requests. Kit doesn't require auth for
+// local stdio usage, so this is a no-op.
+func (a *Agent) Authenticate(_ context.Context, _ acp.AuthenticateRequest) (acp.AuthenticateResponse, error) {
+	return acp.AuthenticateResponse{}, nil
+}
+
+// Initialize negotiates capabilities with the ACP client.
+func (a *Agent) Initialize(_ context.Context, params acp.InitializeRequest) (acp.InitializeResponse, error) {
+	log.Debug("acp: initialize", "protocol_version", params.ProtocolVersion)
+
+	return acp.InitializeResponse{
+		ProtocolVersion: acp.ProtocolVersion(1),
+		AgentCapabilities: acp.AgentCapabilities{
+			LoadSession: true,
+			PromptCapabilities: acp.PromptCapabilities{
+				EmbeddedContext: true,
+				Image:           true,
+			},
+		},
+		AgentInfo: &acp.Implementation{
+			Name:    "Kit",
+			Version: Version,
+		},
+	}, nil
+}
+
+// NewSession creates a new Kit session for the given working directory.
+func (a *Agent) NewSession(ctx context.Context, params acp.NewSessionRequest) (acp.NewSessionResponse, error) {
+	cwd := params.Cwd
+	if cwd == "" {
+		return acp.NewSessionResponse{}, acp.NewInvalidParams("cwd is required")
+	}
+
+	log.Debug("acp: new_session", "cwd", cwd)
+
+	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)
+	}
+
+	return acp.NewSessionResponse{
+		SessionId: acp.SessionId(sess.sessionID),
+	}, nil
+}
+
+// Prompt handles the main agent execution. It subscribes to Kit's event bus,
+// converts events to ACP session updates, and runs the prompt through Kit's
+// full turn lifecycle (hooks, LLM, tool calls, persistence).
+func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.PromptResponse, error) {
+	sessionID := string(params.SessionId)
+	sess, ok := a.registry.get(sessionID)
+	if !ok {
+		return acp.PromptResponse{}, acp.NewInvalidParams(
+			fmt.Sprintf("session not found: %s", sessionID),
+		)
+	}
+
+	// Extract text from prompt content blocks.
+	promptText := extractPromptText(params.Prompt)
+	if promptText == "" {
+		return acp.PromptResponse{}, acp.NewInvalidParams("empty prompt")
+	}
+
+	log.Debug("acp: prompt", "session", sessionID, "prompt_len", len(promptText))
+
+	// Create a cancellable context for this prompt turn.
+	promptCtx, cancel := context.WithCancel(ctx)
+	sess.setCancel(cancel)
+	defer sess.clearCancel()
+
+	// Subscribe to Kit events and stream them as ACP session updates.
+	unsub := a.subscribeEvents(promptCtx, sess.kit, params.SessionId)
+	defer unsub()
+
+	// Run the prompt through Kit's full turn lifecycle.
+	_, err := sess.kit.PromptResult(promptCtx, promptText)
+	if err != nil {
+		if promptCtx.Err() != nil {
+			return acp.PromptResponse{
+				StopReason: acp.StopReasonCancelled,
+			}, nil
+		}
+		return acp.PromptResponse{}, fmt.Errorf("prompt failed: %w", err)
+	}
+
+	return acp.PromptResponse{
+		StopReason: acp.StopReasonEndTurn,
+	}, nil
+}
+
+// Cancel cancels the ongoing prompt for a session.
+func (a *Agent) Cancel(_ context.Context, params acp.CancelNotification) error {
+	sessionID := string(params.SessionId)
+	sess, ok := a.registry.get(sessionID)
+	if !ok {
+		return nil // No-op if session doesn't exist.
+	}
+
+	log.Debug("acp: cancel", "session", sessionID)
+	sess.cancelPrompt()
+	return nil
+}
+
+// SetSessionMode is a no-op for now — Kit doesn't have built-in session modes.
+func (a *Agent) SetSessionMode(_ context.Context, _ acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error) {
+	return acp.SetSessionModeResponse{}, nil
+}
+
+// ---------------------------------------------------------------------------
+// Event streaming: Kit events → ACP SessionUpdate notifications
+// ---------------------------------------------------------------------------
+
+// subscribeEvents subscribes to Kit's event bus and forwards events as ACP
+// session update notifications to the client.
+func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.SessionId) func() {
+	return k.Subscribe(func(e kit.Event) {
+		// Don't send updates after the context is cancelled.
+		if ctx.Err() != nil {
+			return
+		}
+
+		var update *acp.SessionUpdate
+		switch ev := e.(type) {
+		case kit.MessageUpdateEvent:
+			u := acp.UpdateAgentMessageText(ev.Chunk)
+			update = &u
+
+		case kit.ReasoningDeltaEvent:
+			u := acp.UpdateAgentThoughtText(ev.Delta)
+			update = &u
+
+		case kit.ToolCallEvent:
+			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)),
+			)
+			update = &u
+
+		case kit.ToolResultEvent:
+			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
+			}
+			u := acp.UpdateToolCall(tcID,
+				acp.WithUpdateStatus(status),
+				acp.WithUpdateContent([]acp.ToolCallContent{
+					acp.ToolContent(acp.TextBlock(ev.Result)),
+				}),
+			)
+			update = &u
+
+		case kit.ToolCallContentEvent:
+			u := acp.UpdateAgentMessageText(ev.Content)
+			update = &u
+		}
+
+		if update != nil {
+			_ = a.conn.SessionUpdate(ctx, acp.SessionNotification{
+				SessionId: sessionID,
+				Update:    *update,
+			})
+		}
+	})
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// extractPromptText extracts the concatenated text content from ACP content
+// blocks. Non-text blocks are ignored for now.
+func extractPromptText(blocks []acp.ContentBlock) string {
+	var text string
+	for _, block := range blocks {
+		if block.Text != nil {
+			if text != "" {
+				text += "\n"
+			}
+			text += block.Text.Text
+		}
+	}
+	return text
+}
+
+// parseToolArgs attempts to parse a JSON tool args string into a map for
+// structured display. Falls back to a simple string wrapper.
+func parseToolArgs(args string) any {
+	if args == "" {
+		return nil
+	}
+	var m map[string]any
+	if err := json.Unmarshal([]byte(args), &m); err == nil {
+		return m
+	}
+	return map[string]any{"input": args}
+}

internal/acpserver/session.go

@@ -0,0 +1,248 @@
+package acpserver
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/charmbracelet/log"
+
+	"github.com/mark3labs/kit/internal/extensions"
+	kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+// acpSession maps an ACP session to a Kit instance with its own tree session.
+type acpSession struct {
+	kit       *kit.Kit
+	cancelFn  context.CancelFunc // cancels the current prompt
+	cancelMu  sync.Mutex
+	cwd       string
+	sessionID string // Kit-generated session ID (from JSONL header)
+}
+
+// sessionRegistry is a thread-safe registry of ACP session ID → Kit sessions.
+type sessionRegistry struct {
+	mu       sync.RWMutex
+	sessions map[string]*acpSession // ACP session ID → session
+}
+
+func newSessionRegistry() *sessionRegistry {
+	return &sessionRegistry{
+		sessions: make(map[string]*acpSession),
+	}
+}
+
+// create creates a new Kit instance with a persisted tree session for the
+// given working directory. The Kit-generated session ID is used as the ACP
+// session ID so the mapping is 1:1.
+func (r *sessionRegistry) create(ctx context.Context, cwd string) (*acpSession, error) {
+	kitInstance, err := kit.New(ctx, &kit.Options{
+		SessionDir: cwd,
+		Quiet:      true,
+		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)
+	}
+
+	sessionID := kitInstance.GetSessionID()
+	if sessionID == "" {
+		_ = kitInstance.Close()
+		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) {
+				result, err := kitInstance.Subagent(context.Background(), kit.SubagentConfig{
+					Prompt:       config.Prompt,
+					Model:        config.Model,
+					SystemPrompt: config.SystemPrompt,
+					Timeout:      config.Timeout,
+					NoSession:    config.NoSession,
+				})
+				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,
+		sessionID: sessionID,
+	}
+
+	r.mu.Lock()
+	r.sessions[sessionID] = sess
+	r.mu.Unlock()
+
+	return sess, nil
+}
+
+// get retrieves a session by ACP session ID.
+func (r *sessionRegistry) get(sessionID string) (*acpSession, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	s, ok := r.sessions[sessionID]
+	return s, ok
+}
+
+// closeAll closes all sessions.
+func (r *sessionRegistry) closeAll() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for id, sess := range r.sessions {
+		if sess.kit != nil {
+			_ = sess.kit.Close()
+		}
+		delete(r.sessions, id)
+	}
+}
+
+// cancelPrompt cancels the current prompt for a session, if any.
+func (s *acpSession) cancelPrompt() {
+	s.cancelMu.Lock()
+	defer s.cancelMu.Unlock()
+	if s.cancelFn != nil {
+		s.cancelFn()
+		s.cancelFn = nil
+	}
+}
+
+// setCancel stores a cancel function for the current prompt.
+func (s *acpSession) setCancel(cancel context.CancelFunc) {
+	s.cancelMu.Lock()
+	defer s.cancelMu.Unlock()
+	s.cancelFn = cancel
+}
+
+// clearCancel clears the stored cancel function (called when prompt completes).
+func (s *acpSession) clearCancel() {
+	s.cancelMu.Lock()
+	defer s.cancelMu.Unlock()
+	s.cancelFn = nil
+}

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 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)
@@ -58,6 +60,9 @@ type StreamingResponseHandler func(content string)
 // ToolCallContentHandler is a function type for handling content that accompanies tool calls.
 type ToolCallContentHandler func(content string)
 
+// ReasoningDeltaHandler is a function type for handling streaming reasoning/thinking deltas.
+type ReasoningDeltaHandler func(delta string)
+
 // Agent represents an AI agent with core tool integration using the fantasy library.
 // Core tools (bash, read, write, edit, grep, find, ls) are registered as direct
 // fantasy.AgentTool implementations — no MCP layer, no serialization overhead.
@@ -87,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.
@@ -157,6 +164,27 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 		))
 	}
 
+	// Pass provider-specific options (e.g. OpenAI Responses API reasoning settings).
+	if providerResult.ProviderOptions != nil {
+		agentOpts = append(agentOpts, fantasy.WithProviderOptions(providerResult.ProviderOptions))
+	}
+
+	// Pass generation parameters when available.
+	if agentConfig.ModelConfig != nil {
+		if agentConfig.ModelConfig.MaxTokens > 0 {
+			agentOpts = append(agentOpts, fantasy.WithMaxOutputTokens(int64(agentConfig.ModelConfig.MaxTokens)))
+		}
+		if agentConfig.ModelConfig.Temperature != nil {
+			agentOpts = append(agentOpts, fantasy.WithTemperature(float64(*agentConfig.ModelConfig.Temperature)))
+		}
+		if agentConfig.ModelConfig.TopP != nil {
+			agentOpts = append(agentOpts, fantasy.WithTopP(float64(*agentConfig.ModelConfig.TopP)))
+		}
+		if agentConfig.ModelConfig.TopK != nil {
+			agentOpts = append(agentOpts, fantasy.WithTopK(int64(*agentConfig.ModelConfig.TopK)))
+		}
+	}
+
 	// Create the fantasy agent
 	fantasyAgent := fantasy.NewAgent(providerResult.Model, agentOpts...)
 
@@ -190,7 +218,7 @@ func (a *Agent) GenerateWithLoop(ctx context.Context, messages []fantasy.Message
 	onResponse ResponseHandler, onToolCallContent ToolCallContentHandler,
 ) (*GenerateWithLoopResult, error) {
 	return a.GenerateWithLoopAndStreaming(ctx, messages, onToolCall, onToolExecution, onToolResult,
-		onResponse, onToolCallContent, nil)
+		onResponse, onToolCallContent, nil, nil)
 }
 
 // GenerateWithLoopAndStreaming processes messages using the fantasy agent with streaming and callbacks.
@@ -200,11 +228,14 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 	onToolCall ToolCallHandler, onToolExecution ToolExecutionHandler, onToolResult ToolResultHandler,
 	onResponse ResponseHandler, onToolCallContent ToolCallContentHandler,
 	onStreamingResponse StreamingResponseHandler,
+	onReasoningDelta ReasoningDeltaHandler,
 ) (*GenerateWithLoopResult, error) {
 
 	// Fantasy requires the current user input as Prompt, with prior messages as history.
-	// Extract the last user message text as the prompt, and pass everything before it as Messages.
-	prompt, history := splitPromptAndHistory(messages)
+	// Extract the last user message text and files as the prompt, and pass everything
+	// before it as Messages. Files (e.g. clipboard images) are passed via the Files
+	// field so Fantasy includes them in the API request.
+	prompt, files, history := splitPromptAndHistory(messages)
 
 	// Track current tool call info for callbacks
 	var currentToolName string
@@ -215,14 +246,26 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 	// Stream is required to observe tool execution in real time. The non-streaming
 	// Generate path is reserved for the simple case with no callbacks at all.
 	hasCallbacks := onToolCall != nil || onToolExecution != nil || onToolResult != nil ||
-		onToolCallContent != nil || onStreamingResponse != nil
+		onToolCallContent != nil || onStreamingResponse != nil || onReasoningDelta != nil
 
 	if a.streamingEnabled || hasCallbacks {
 		// Use fantasy's streaming agent
 		result, err := a.fantasyAgent.Stream(ctx, fantasy.AgentStreamCall{
 			Prompt:   prompt,
+			Files:    files,
 			Messages: history,
 
+			// Reasoning/thinking streaming callback
+			OnReasoningDelta: func(id, delta string) error {
+				if ctx.Err() != nil {
+					return ctx.Err()
+				}
+				if onReasoningDelta != nil {
+					onReasoningDelta(delta)
+				}
+				return nil
+			},
+
 			// Text streaming callback
 			OnTextDelta: func(id, text string) error {
 				if ctx.Err() != nil {
@@ -244,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, true)
+					onToolExecution(tc.ToolCallID, tc.ToolName, tc.Input, true)
 				}
 
 				return nil
@@ -262,13 +305,13 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				}
 				// Notify tool execution finished
 				if onToolExecution != nil {
-					onToolExecution(tr.ToolName, 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
@@ -304,6 +347,7 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 	// Non-streaming path with no callbacks — use the simpler Generate call.
 	result, err := a.fantasyAgent.Generate(ctx, fantasy.AgentCall{
 		Prompt:   prompt,
+		Files:    files,
 		Messages: history,
 	})
 	if err != nil {
@@ -324,27 +368,32 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 // and returns everything before it as conversation history. Fantasy's agent
 // requires the current turn's input as Prompt (string), with prior messages
 // passed separately as Messages (history).
-func splitPromptAndHistory(messages []fantasy.Message) (string, []fantasy.Message) {
+func splitPromptAndHistory(messages []fantasy.Message) (string, []fantasy.FilePart, []fantasy.Message) {
 	if len(messages) == 0 {
-		return "", nil
+		return "", nil, nil
 	}
 
 	// Walk backwards to find the last user message
 	for i := len(messages) - 1; i >= 0; i-- {
 		if messages[i].Role == fantasy.MessageRoleUser {
-			// Extract text from the user message parts
+			// Extract text and file parts from the user message
 			var prompt string
+			var files []fantasy.FilePart
 			for _, part := range messages[i].Content {
-				if tp, ok := part.(fantasy.TextPart); ok {
-					prompt = tp.Text
-					break
+				switch p := part.(type) {
+				case fantasy.TextPart:
+					if prompt == "" {
+						prompt = p.Text
+					}
+				case fantasy.FilePart:
+					files = append(files, p)
 				}
 			}
 			// History is everything except this last user message
 			history := make([]fantasy.Message, 0, len(messages)-1)
 			history = append(history, messages[:i]...)
 			history = append(history, messages[i+1:]...)
-			return prompt, history
+			return prompt, files, history
 		}
 	}
 
@@ -352,11 +401,11 @@ func splitPromptAndHistory(messages []fantasy.Message) (string, []fantasy.Messag
 	last := messages[len(messages)-1]
 	for _, part := range last.Content {
 		if tp, ok := part.(fantasy.TextPart); ok {
-			return tp.Text, messages[:len(messages)-1]
+			return tp.Text, nil, messages[:len(messages)-1]
 		}
 	}
 
-	return "", messages
+	return "", nil, messages
 }
 
 // convertAgentResult converts a fantasy AgentResult to our GenerateWithLoopResult.
@@ -381,6 +430,7 @@ func convertAgentResult(result *fantasy.AgentResult, originalMessages []fantasy.
 		ConversationMessages: allFantasyMessages,
 		Messages:             allMessages,
 		TotalUsage:           result.TotalUsage,
+		StopReason:           string(result.Response.FinishReason),
 	}
 }
 
@@ -524,6 +574,25 @@ func (a *Agent) SetModel(ctx context.Context, config *models.ProviderConfig) err
 		))
 	}
 
+	// Pass provider-specific options (e.g. OpenAI Responses API reasoning settings).
+	if providerResult.ProviderOptions != nil {
+		agentOpts = append(agentOpts, fantasy.WithProviderOptions(providerResult.ProviderOptions))
+	}
+
+	// Pass generation parameters when available.
+	if config.MaxTokens > 0 {
+		agentOpts = append(agentOpts, fantasy.WithMaxOutputTokens(int64(config.MaxTokens)))
+	}
+	if config.Temperature != nil {
+		agentOpts = append(agentOpts, fantasy.WithTemperature(float64(*config.Temperature)))
+	}
+	if config.TopP != nil {
+		agentOpts = append(agentOpts, fantasy.WithTopP(float64(*config.TopP)))
+	}
+	if config.TopK != nil {
+		agentOpts = append(agentOpts, fantasy.WithTopK(int64(*config.TopK)))
+	}
+
 	newFantasyAgent := fantasy.NewAgent(providerResult.Model, agentOpts...)
 
 	// Close old provider.

internal/app/app.go

@@ -13,6 +13,12 @@ import (
 	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
+// queueItem holds a prompt and optional image attachments for the execution queue.
+type queueItem struct {
+	Prompt string
+	Files  []fantasy.FilePart
+}
+
 // App is the application-layer orchestrator. It owns the agentic loop,
 // conversation history (via MessageStore), and queue management. It is
 // designed to be created once per session and reused across multiple prompts.
@@ -47,7 +53,7 @@ type App struct {
 	// mu protects busy, queue, and cancelStep.
 	mu    sync.Mutex
 	busy  bool
-	queue []string
+	queue []queueItem
 
 	// wg tracks in-flight goroutines; Close() waits on it.
 	wg sync.WaitGroup
@@ -100,6 +106,16 @@ func (a *App) SetProgram(p *tea.Program) {
 //
 // Satisfies ui.AppController.
 func (a *App) Run(prompt string) int {
+	return a.RunWithFiles(prompt, nil)
+}
+
+// RunWithFiles queues a multimodal prompt (text + image files) for execution.
+// If the app is idle the prompt executes immediately; otherwise it is queued.
+// Returns the current queue depth (0 = started immediately, >0 = queued).
+//
+// Satisfies ui.AppController (via RunWithImages which converts ImageAttachment
+// to fantasy.FilePart).
+func (a *App) RunWithFiles(prompt string, files []fantasy.FilePart) int {
 	a.mu.Lock()
 
 	if a.closed {
@@ -107,8 +123,10 @@ func (a *App) Run(prompt string) int {
 		return 0
 	}
 
+	item := queueItem{Prompt: prompt, Files: files}
+
 	if a.busy {
-		a.queue = append(a.queue, prompt)
+		a.queue = append(a.queue, item)
 		qLen := len(a.queue)
 		a.mu.Unlock()
 		return qLen
@@ -117,7 +135,7 @@ func (a *App) Run(prompt string) int {
 	a.busy = true
 	a.wg.Add(1)
 	a.mu.Unlock()
-	go a.drainQueue(prompt)
+	go a.drainQueue(item)
 	return 0
 }
 
@@ -153,17 +171,19 @@ func (a *App) Steer(prompt string) {
 		return
 	}
 
+	item := queueItem{Prompt: prompt}
+
 	if !a.busy {
 		// Not busy — start immediately, same as Run().
 		a.busy = true
 		a.wg.Add(1)
 		a.mu.Unlock()
-		go a.drainQueue(prompt)
+		go a.drainQueue(item)
 		return
 	}
 
 	// Agent is busy: clear queue, insert steer message, then cancel.
-	a.queue = []string{prompt}
+	a.queue = []queueItem{item}
 	cancel := a.cancelStep
 	a.mu.Unlock()
 	cancel()
@@ -197,6 +217,22 @@ func (a *App) GetTreeSession() *session.TreeManager {
 	return a.opts.TreeSession
 }
 
+// AddContextMessage adds a user-role message to the conversation history
+// without triggering an LLM response. Used by the ! shell command prefix
+// to inject command output into context so the LLM can reference it in
+// subsequent turns.
+//
+// Satisfies ui.AppController.
+func (a *App) AddContextMessage(text string) {
+	msg := fantasy.NewUserMessage(text)
+	a.store.Add(msg)
+
+	// Persist to tree session if active.
+	if ts := a.opts.TreeSession; ts != nil {
+		_, _ = ts.AppendFantasyMessage(msg)
+	}
+}
+
 // CompactConversation summarises older messages to free context space. It
 // returns an error synchronously if compaction cannot start (agent busy or
 // app closed). The actual compaction runs in a background goroutine and
@@ -271,7 +307,7 @@ func (a *App) RunOnce(ctx context.Context, prompt string) error {
 	a.cancelStep = cancel
 	a.mu.Unlock()
 
-	result, err := a.executeStep(stepCtx, prompt, nil)
+	result, err := a.executeStep(stepCtx, prompt, nil, nil)
 	if err != nil {
 		return err
 	}
@@ -293,7 +329,7 @@ func (a *App) RunOnceResult(ctx context.Context, prompt string) (*kit.TurnResult
 	a.cancelStep = cancel
 	a.mu.Unlock()
 
-	return a.executeStep(stepCtx, prompt, nil)
+	return a.executeStep(stepCtx, prompt, nil, nil)
 }
 
 // RunOnceWithDisplay executes a single agent step synchronously, sending
@@ -314,7 +350,7 @@ func (a *App) RunOnceWithDisplay(ctx context.Context, prompt string, eventFn fun
 	a.cancelStep = cancel
 	a.mu.Unlock()
 
-	result, err := a.executeStep(stepCtx, prompt, eventFn)
+	result, err := a.executeStep(stepCtx, prompt, eventFn, nil)
 	if err != nil {
 		return err
 	}
@@ -355,15 +391,15 @@ func (a *App) Close() {
 // Internal: queue drain loop
 // --------------------------------------------------------------------------
 
-// drainQueue runs in a goroutine. It executes the given prompt and then
+// drainQueue runs in a goroutine. It executes the given item and then
 // continues draining the queue until it is empty.
 // Must be called with a.busy == true and a.wg incremented.
-func (a *App) drainQueue(firstPrompt string) {
+func (a *App) drainQueue(first queueItem) {
 	defer a.wg.Done()
 
-	prompt := firstPrompt
+	item := first
 	for {
-		a.runPrompt(prompt)
+		a.runQueueItem(item)
 
 		a.mu.Lock()
 		// Stop draining if the app is shutting down.
@@ -378,7 +414,7 @@ func (a *App) drainQueue(firstPrompt string) {
 			a.mu.Unlock()
 			return
 		}
-		prompt = a.queue[0]
+		item = a.queue[0]
 		a.queue = a.queue[1:]
 		qLen := len(a.queue)
 		a.mu.Unlock()
@@ -387,9 +423,9 @@ func (a *App) drainQueue(firstPrompt string) {
 	}
 }
 
-// runPrompt executes a single prompt: adds the user message to the store,
+// runQueueItem executes a single queue item: adds the user message to the store,
 // runs the agent step, and sends the appropriate event to the program.
-func (a *App) runPrompt(prompt string) {
+func (a *App) runQueueItem(item queueItem) {
 	// Create a per-step cancellable context.
 	stepCtx, cancel := context.WithCancel(a.rootCtx)
 	a.mu.Lock()
@@ -408,7 +444,7 @@ func (a *App) runPrompt(prompt string) {
 		}
 	}
 
-	result, err := a.executeStep(stepCtx, prompt, eventFn)
+	result, err := a.executeStep(stepCtx, item.Prompt, eventFn, item.Files)
 	if err != nil {
 		if stepCtx.Err() != nil {
 			// Step was cancelled by the user (e.g. double-ESC). Send a
@@ -429,9 +465,9 @@ func (a *App) runPrompt(prompt string) {
 // --------------------------------------------------------------------------
 
 // executeStep runs a single agentic step by delegating to the SDK's
-// PromptResult(), which handles session persistence, hooks, extension
-// events, and the generation loop.
-func (a *App) executeStep(ctx context.Context, prompt string, eventFn func(tea.Msg)) (*kit.TurnResult, error) {
+// PromptResult() (or PromptResultWithFiles for multimodal), which handles
+// session persistence, hooks, extension events, and the generation loop.
+func (a *App) executeStep(ctx context.Context, prompt string, eventFn func(tea.Msg), files []fantasy.FilePart) (*kit.TurnResult, error) {
 	// Test hook: bypass SDK entirely.
 	if a.opts.PromptFunc != nil {
 		return a.opts.PromptFunc(ctx, prompt)
@@ -451,7 +487,13 @@ func (a *App) executeStep(ctx context.Context, prompt string, eventFn func(tea.M
 	// Show spinner while the agent works.
 	sendFn(SpinnerEvent{Show: true})
 
-	result, err := a.opts.Kit.PromptResult(ctx, prompt)
+	var result *kit.TurnResult
+	var err error
+	if len(files) > 0 {
+		result, err = a.opts.Kit.PromptResultWithFiles(ctx, prompt, files)
+	} else {
+		result, err = a.opts.Kit.PromptResult(ctx, prompt)
+	}
 	if err != nil {
 		return nil, err
 	}
@@ -490,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, 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:
@@ -506,6 +548,8 @@ func (a *App) subscribeSDKEvents(sendFn func(tea.Msg)) func() {
 			sendFn(ResponseCompleteEvent{Content: ev.Content})
 		case kit.MessageUpdateEvent:
 			sendFn(StreamChunkEvent{Content: ev.Chunk})
+		case kit.ReasoningDeltaEvent:
+			sendFn(ReasoningChunkEvent{Delta: ev.Delta})
 		}
 	}))
 

internal/app/app_test.go

@@ -494,7 +494,11 @@ func TestQueueLength_reflects(t *testing.T) {
 	}
 
 	app.mu.Lock()
-	app.queue = append(app.queue, "a", "b", "c")
+	app.queue = append(app.queue,
+		queueItem{Prompt: "a"},
+		queueItem{Prompt: "b"},
+		queueItem{Prompt: "c"},
+	)
 	app.mu.Unlock()
 
 	if got := app.QueueLength(); got != 3 {

internal/app/events.go

@@ -9,9 +9,18 @@ type StreamChunkEvent struct {
 	Content string
 }
 
+// ReasoningChunkEvent is sent when a streaming reasoning/thinking delta arrives
+// from the LLM. Thinking content is rendered separately from regular text.
+type ReasoningChunkEvent struct {
+	// Delta is the incremental reasoning text from the streaming response.
+	Delta string
+}
+
 // 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.
@@ -21,14 +30,20 @@ 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).
+	ToolArgs string
 	// IsStarting is true when execution is beginning, false when it is complete.
 	IsStarting bool
 }
 
 // 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/clipboard/clipboard.go

@@ -0,0 +1,75 @@
+// Package clipboard provides cross-platform clipboard image reading for Kit.
+//
+// Terminals cannot paste binary image data via bracketed paste — only text is
+// supported. To read images we shell out to platform-specific clipboard tools:
+//
+//   - Linux X11:  xclip -selection clipboard -t image/png -o
+//   - Linux Wayland: wl-paste --type image/png
+//   - macOS: osascript + pbpaste (via a helper that reads NSPasteboard)
+//   - Windows/WSL: powershell Get-Clipboard -Format Image (not yet supported)
+//
+// The ReadImage function returns the raw image bytes and detected MIME type,
+// or an error if no image is available on the clipboard.
+package clipboard
+
+import (
+	"fmt"
+)
+
+// ImageData holds the result of a clipboard image read.
+type ImageData struct {
+	// Data is the raw image bytes (PNG, JPEG, etc.).
+	Data []byte
+	// MediaType is the MIME type (e.g. "image/png", "image/jpeg").
+	MediaType string
+}
+
+// DetectMediaType inspects the magic bytes of data to determine the image
+// MIME type. Returns empty string if the format is not recognized.
+func DetectMediaType(data []byte) string {
+	if len(data) < 8 {
+		return ""
+	}
+
+	// PNG: 89 50 4E 47 0D 0A 1A 0A
+	if data[0] == 0x89 && data[1] == 0x50 && data[2] == 0x4E && data[3] == 0x47 &&
+		data[4] == 0x0D && data[5] == 0x0A && data[6] == 0x1A && data[7] == 0x0A {
+		return "image/png"
+	}
+
+	// JPEG: FF D8 FF
+	if data[0] == 0xFF && data[1] == 0xD8 && data[2] == 0xFF {
+		return "image/jpeg"
+	}
+
+	// GIF: 47 49 46 38
+	if data[0] == 0x47 && data[1] == 0x49 && data[2] == 0x46 && data[3] == 0x38 {
+		return "image/gif"
+	}
+
+	// WebP: RIFF....WEBP
+	if len(data) >= 12 &&
+		data[0] == 0x52 && data[1] == 0x49 && data[2] == 0x46 && data[3] == 0x46 &&
+		data[8] == 0x57 && data[9] == 0x45 && data[10] == 0x42 && data[11] == 0x50 {
+		return "image/webp"
+	}
+
+	// BMP: 42 4D
+	if data[0] == 0x42 && data[1] == 0x4D {
+		return "image/bmp"
+	}
+
+	// TIFF: 49 49 2A 00 (little-endian) or 4D 4D 00 2A (big-endian)
+	if (data[0] == 0x49 && data[1] == 0x49 && data[2] == 0x2A && data[3] == 0x00) ||
+		(data[0] == 0x4D && data[1] == 0x4D && data[2] == 0x00 && data[3] == 0x2A) {
+		return "image/tiff"
+	}
+
+	return ""
+}
+
+// ErrNoImage is returned when the clipboard does not contain image data.
+var ErrNoImage = fmt.Errorf("no image data on clipboard")
+
+// ErrNoClipboardTool is returned when no suitable clipboard tool is found.
+var ErrNoClipboardTool = fmt.Errorf("no clipboard tool available (install xclip, wl-paste, or use macOS)")

internal/clipboard/clipboard_darwin.go

@@ -0,0 +1,45 @@
+//go:build darwin
+
+package clipboard
+
+import (
+	"os/exec"
+)
+
+// ReadImage reads image data from the system clipboard on macOS.
+// It uses osascript to check if the clipboard contains an image and then
+// reads the data using a temporary approach. If the clipboard contains
+// an image, it writes it to stdout as PNG data.
+func ReadImage() (*ImageData, error) {
+	// Use osascript to write clipboard image to stdout via a pipe.
+	// The script checks if the clipboard has a «class PNGf» item.
+	script := `use framework "AppKit"
+set pb to current application's NSPasteboard's generalPasteboard()
+set imgData to pb's dataForType:(current application's NSPasteboardTypePNG)
+if imgData is missing value then
+	set tiffData to pb's dataForType:(current application's NSPasteboardTypeTIFF)
+	if tiffData is missing value then
+		error "No image on clipboard"
+	end if
+	set bitmapRep to current application's NSBitmapImageRep's imageRepWithData:tiffData
+	set imgData to bitmapRep's representationUsingType:(current application's NSPNGFileType) |properties|:(missing value)
+end if
+imgData's writeToFile:"/dev/stdout" atomically:false`
+
+	cmd := exec.Command("osascript", "-l", "AppleScript", "-e", script)
+	data, err := cmd.Output()
+	if err != nil {
+		return nil, ErrNoImage
+	}
+
+	if len(data) == 0 {
+		return nil, ErrNoImage
+	}
+
+	mediaType := DetectMediaType(data)
+	if mediaType == "" {
+		mediaType = "image/png" // osascript converts to PNG
+	}
+
+	return &ImageData{Data: data, MediaType: mediaType}, nil
+}

internal/clipboard/clipboard_integration_test.go

@@ -0,0 +1,80 @@
+//go:build integration
+
+package clipboard_test
+
+import (
+	"os"
+	"testing"
+
+	"github.com/mark3labs/kit/internal/clipboard"
+)
+
+// TestReadImageIntegration tests reading an image from the system clipboard.
+// Run with: WAYLAND_DISPLAY=wayland-1 go test -tags integration -v -run TestReadImageIntegration ./internal/clipboard/
+//
+// Prerequisites: copy an image to the clipboard first, e.g.:
+//
+//	WAYLAND_DISPLAY=wayland-1 wl-copy --type image/png < ~/Pictures/Screenshots/some_screenshot.png
+func TestReadImageIntegration(t *testing.T) {
+	if os.Getenv("WAYLAND_DISPLAY") == "" && os.Getenv("DISPLAY") == "" {
+		t.Skip("no display server available (set WAYLAND_DISPLAY or DISPLAY)")
+	}
+
+	img, err := clipboard.ReadImage()
+	if err != nil {
+		t.Fatalf("ReadImage() error: %v", err)
+	}
+
+	if img == nil {
+		t.Fatal("ReadImage() returned nil without error")
+	}
+
+	t.Logf("Image data: %d bytes", len(img.Data))
+	t.Logf("Media type: %s", img.MediaType)
+
+	if len(img.Data) == 0 {
+		t.Fatal("image data is empty")
+	}
+
+	if img.MediaType == "" {
+		t.Fatal("media type is empty")
+	}
+
+	// Verify magic bytes match the declared media type.
+	detected := clipboard.DetectMediaType(img.Data)
+	if detected == "" {
+		t.Fatal("could not detect image format from magic bytes")
+	}
+	t.Logf("Detected format: %s", detected)
+
+	if detected != img.MediaType {
+		t.Errorf("media type mismatch: declared=%s detected=%s", img.MediaType, detected)
+	}
+}
+
+func TestDetectMediaType(t *testing.T) {
+	tests := []struct {
+		name     string
+		data     []byte
+		expected string
+	}{
+		{"PNG", []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00}, "image/png"},
+		{"JPEG", []byte{0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49}, "image/jpeg"},
+		{"GIF", []byte{0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x00, 0x00, 0x00}, "image/gif"},
+		{"BMP", []byte{0x42, 0x4D, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}, "image/bmp"},
+		{"WebP", []byte{0x52, 0x49, 0x46, 0x46, 0x00, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50}, "image/webp"},
+		{"TIFF-LE", []byte{0x49, 0x49, 0x2A, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}, "image/tiff"},
+		{"TIFF-BE", []byte{0x4D, 0x4D, 0x00, 0x2A, 0x00, 0x00, 0x00, 0x00, 0x00}, "image/tiff"},
+		{"unknown", []byte{0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08}, ""},
+		{"too short", []byte{0x89, 0x50}, ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := clipboard.DetectMediaType(tt.data)
+			if got != tt.expected {
+				t.Errorf("DetectMediaType() = %q, want %q", got, tt.expected)
+			}
+		})
+	}
+}

internal/clipboard/clipboard_linux.go

@@ -0,0 +1,57 @@
+//go:build linux
+
+package clipboard
+
+import (
+	"os/exec"
+)
+
+// ReadImage reads image data from the system clipboard on Linux.
+// It tries xclip first (X11), then falls back to wl-paste (Wayland).
+func ReadImage() (*ImageData, error) {
+	// Try xclip first (X11).
+	if path, err := exec.LookPath("xclip"); err == nil {
+		data, err := readWithXclip(path)
+		if err == nil && len(data) > 0 {
+			mediaType := DetectMediaType(data)
+			if mediaType == "" {
+				mediaType = "image/png" // xclip was asked for image/png
+			}
+			return &ImageData{Data: data, MediaType: mediaType}, nil
+		}
+	}
+
+	// Fallback to wl-paste (Wayland).
+	if path, err := exec.LookPath("wl-paste"); err == nil {
+		data, err := readWithWlPaste(path)
+		if err == nil && len(data) > 0 {
+			mediaType := DetectMediaType(data)
+			if mediaType == "" {
+				mediaType = "image/png"
+			}
+			return &ImageData{Data: data, MediaType: mediaType}, nil
+		}
+	}
+
+	// Check if either tool exists but just had no image.
+	if _, err := exec.LookPath("xclip"); err == nil {
+		return nil, ErrNoImage
+	}
+	if _, err := exec.LookPath("wl-paste"); err == nil {
+		return nil, ErrNoImage
+	}
+
+	return nil, ErrNoClipboardTool
+}
+
+// readWithXclip reads image data using xclip.
+func readWithXclip(xclipPath string) ([]byte, error) {
+	cmd := exec.Command(xclipPath, "-selection", "clipboard", "-t", "image/png", "-o")
+	return cmd.Output()
+}
+
+// readWithWlPaste reads image data using wl-paste.
+func readWithWlPaste(wlPastePath string) ([]byte, error) {
+	cmd := exec.Command(wlPastePath, "--type", "image/png")
+	return cmd.Output()
+}

internal/clipboard/clipboard_windows.go

@@ -0,0 +1,9 @@
+//go:build windows
+
+package clipboard
+
+// ReadImage reads image data from the system clipboard on Windows.
+// Windows clipboard image support is not yet implemented.
+func ReadImage() (*ImageData, error) {
+	return nil, ErrNoClipboardTool
+}

internal/config/config.go

@@ -165,6 +165,9 @@ type Config struct {
 	TopK          *int32   `json:"top-k,omitempty" yaml:"top-k,omitempty"`
 	StopSequences []string `json:"stop-sequences,omitempty" yaml:"stop-sequences,omitempty"`
 
+	// Thinking / extended reasoning
+	ThinkingLevel string `json:"thinking-level,omitempty" yaml:"thinking-level,omitempty"`
+
 	// TLS configuration
 	TLSSkipVerify bool `json:"tls-skip-verify,omitempty" yaml:"tls-skip-verify,omitempty"`
 }

internal/core/bash.go

@@ -130,7 +130,7 @@ func executeBash(ctx context.Context, call fantasy.ToolCall, workDir string) (fa
 	}
 
 	// Truncate from tail (keep last N lines, most relevant for bash)
-	tr := truncateTail(output, defaultMaxLines, defaultMaxBytes)
+	tr := TruncateTail(output, defaultMaxLines, defaultMaxBytes)
 
 	if exitCode != 0 {
 		return fantasy.NewTextErrorResponse(tr.Content), nil

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/find.go

@@ -39,6 +39,7 @@ func NewFindTool(opts ...ToolOption) fantasy.AgentTool {
 				},
 			},
 			Required: []string{"pattern"},
+			Parallel: true,
 		},
 		handler: func(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
 			return executeFind(ctx, call, cfg.WorkDir)

internal/core/grep.go

@@ -59,6 +59,7 @@ func NewGrepTool(opts ...ToolOption) fantasy.AgentTool {
 				},
 			},
 			Required: []string{"pattern"},
+			Parallel: true,
 		},
 		handler: func(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
 			return executeGrep(ctx, call, cfg.WorkDir)

internal/core/ls.go

@@ -33,6 +33,7 @@ func NewLsTool(opts ...ToolOption) fantasy.AgentTool {
 				},
 			},
 			Required: []string{},
+			Parallel: true,
 		},
 		handler: func(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
 			return executeLs(ctx, call, cfg.WorkDir)

internal/core/read.go

@@ -38,6 +38,7 @@ func NewReadTool(opts ...ToolOption) fantasy.AgentTool {
 				},
 			},
 			Required: []string{"path"},
+			Parallel: true,
 		},
 		handler: func(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
 			return executeRead(ctx, call, cfg.WorkDir)

internal/core/subagent.go

@@ -0,0 +1,171 @@
+package core
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"charm.land/fantasy"
+)
+
+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"`
+	SystemPrompt   string `json:"system_prompt,omitempty"`
+	TimeoutSeconds int    `json:"timeout_seconds,omitempty"`
+}
+
+// NewSubagentTool creates the spawn_subagent core tool.
+func NewSubagentTool(opts ...ToolOption) fantasy.AgentTool {
+	return &coreTool{
+		info: fantasy.ToolInfo{
+			Name: "spawn_subagent",
+			Description: `Spawn a subagent to perform a task autonomously.
+
+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
+
+The subagent result is returned when it completes. For long-running tasks,
+consider breaking them into smaller focused subtasks.
+
+Example use cases:
+- "Research the authentication patterns in this codebase"
+- "Write unit tests for the UserService class"
+- "Analyze the performance bottlenecks in the database queries"`,
+			Parameters: map[string]any{
+				"task": map[string]any{
+					"type":        "string",
+					"description": "The complete task description for the subagent to perform",
+				},
+				"model": map[string]any{
+					"type":        "string",
+					"description": "Optional model override (e.g. 'anthropic/claude-haiku-3-5-20241022' for faster/cheaper tasks)",
+				},
+				"system_prompt": map[string]any{
+					"type":        "string",
+					"description": "Optional system prompt for domain-specific guidance",
+				},
+				"timeout_seconds": map[string]any{
+					"type":        "number",
+					"description": "Maximum execution time in seconds (default: 300, max: 1800)",
+				},
+			},
+			Required: []string{"task"},
+			Parallel: true,
+		},
+		handler: func(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			return executeSubagent(ctx, call)
+		},
+	}
+}
+
+func executeSubagent(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
+	var args subagentArgs
+	if err := parseArgs(call.Input, &args); err != nil {
+		return fantasy.NewTextErrorResponse("task parameter is required"), nil
+	}
+	if args.Task == "" {
+		return fantasy.NewTextErrorResponse("task parameter is required"), nil
+	}
+
+	// Determine timeout.
+	timeout := defaultSubagentTimeout
+	if args.TimeoutSeconds > 0 {
+		timeout = min(time.Duration(args.TimeoutSeconds)*time.Second, maxSubagentTimeout)
+	}
+
+	// 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")
+	}
+
+	// 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.
+	response := fmt.Sprintf("Subagent completed successfully in %ds.", int(result.Elapsed.Seconds()))
+	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))
+
+	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.
+func truncateResponse(s string, maxLen int) string {
+	if len(s) <= maxLen {
+		return s
+	}
+	return s[:maxLen] + "\n\n... [truncated — " + fmt.Sprintf("%d", len(s)-maxLen) + " bytes omitted]"
+}

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...),
@@ -98,3 +99,8 @@ func AllTools(opts ...ToolOption) []fantasy.AgentTool {
 		NewLsTool(opts...),
 	}
 }
+
+// AllTools returns all available core tools.
+func AllTools(opts ...ToolOption) []fantasy.AgentTool {
+	return append(SubagentTools(opts...), NewSubagentTool(opts...))
+}

internal/core/truncate.go

@@ -9,6 +9,11 @@ const (
 	defaultMaxLines = 2000
 	defaultMaxBytes = 50 * 1024 // 50KB
 	grepMaxLineLen  = 500
+
+	// DefaultMaxLines is the exported default line limit for truncation.
+	DefaultMaxLines = defaultMaxLines
+	// DefaultMaxBytes is the exported default byte limit for truncation.
+	DefaultMaxBytes = defaultMaxBytes
 )
 
 // TruncationResult describes how output was truncated.
@@ -20,9 +25,9 @@ type TruncationResult struct {
 	Kept      int    // lines kept after truncation
 }
 
-// truncateTail keeps the last maxLines lines and at most maxBytes bytes.
+// TruncateTail keeps the last maxLines lines and at most maxBytes bytes.
 // Used for bash output where the tail is most relevant.
-func truncateTail(content string, maxLines, maxBytes int) TruncationResult {
+func TruncateTail(content string, maxLines, maxBytes int) TruncationResult {
 	if maxLines <= 0 {
 		maxLines = defaultMaxLines
 	}

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

@@ -491,6 +491,41 @@ type Context struct {
 	//       },
 	//   })
 	ReloadExtensions func() error
+
+	// SpawnSubagent spawns a child Kit instance to perform a task autonomously.
+	// The subagent runs as a separate subprocess with full tool access but
+	// isolated session and extensions (--no-session --no-extensions).
+	//
+	// When config.Blocking is true, blocks until completion and returns the
+	// result directly (handle is nil). When false, returns immediately with
+	// a handle for monitoring/cancellation.
+	//
+	// Example — blocking call:
+	//
+	//   _, result, err := ctx.SpawnSubagent(ext.SubagentConfig{
+	//       Prompt:   "Research authentication patterns in this codebase",
+	//       Blocking: true,
+	//       Timeout:  2 * time.Minute,
+	//   })
+	//   if err != nil {
+	//       ctx.PrintError("spawn failed: " + err.Error())
+	//       return
+	//   }
+	//   ctx.PrintInfo("Subagent result:\n" + result.Response)
+	//
+	// Example — background spawn with callbacks:
+	//
+	//   handle, _, _ := ctx.SpawnSubagent(ext.SubagentConfig{
+	//       Prompt: "Write unit tests for UserService",
+	//       OnOutput: func(chunk string) {
+	//           // Live output streaming
+	//       },
+	//       OnComplete: func(result ext.SubagentResult) {
+	//           ctx.SendMessage("Subagent finished:\n" + result.Response)
+	//       },
+	//   })
+	//   // handle.Kill() to cancel, handle.Wait() to block
+	SpawnSubagent func(SubagentConfig) (*SubagentHandle, *SubagentResult, error)
 }
 
 // ---------------------------------------------------------------------------
@@ -1397,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".
@@ -1416,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

@@ -0,0 +1,345 @@
+// Package extensions provides subagent spawning capabilities for Kit extensions.
+package extensions
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// ---------------------------------------------------------------------------
+// Subagent types
+// ---------------------------------------------------------------------------
+
+// SubagentConfig configures a subagent spawn.
+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.
+	// Empty string uses the default system prompt.
+	SystemPrompt string
+
+	// Timeout limits execution time. Zero means 5 minute default.
+	Timeout time.Duration
+
+	// OnOutput streams stderr output chunks as the subagent runs.
+	// Called from a goroutine; must be safe for concurrent use.
+	OnOutput func(chunk string)
+
+	// OnComplete is called when the subagent finishes (success or error).
+	// Called from a goroutine; must be safe for concurrent use.
+	OnComplete func(result SubagentResult)
+
+	// Blocking, when true, makes SpawnSubagent wait for completion and
+	// return the result directly. When false (default), spawns in background
+	// 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 header includes a parent reference
+	// so viewers can navigate the session tree.
+	ParentSessionID string
+}
+
+// SubagentResult contains the outcome of a 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
+
+	// ExitCode is the subprocess exit code (0 = success).
+	ExitCode int
+
+	// Elapsed is the total execution time.
+	Elapsed time.Duration
+
+	// 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.
+type SubagentUsage struct {
+	InputTokens  int64
+	OutputTokens int64
+}
+
+// SubagentHandle provides control over a running subagent.
+type SubagentHandle struct {
+	// ID is a unique identifier for this subagent instance.
+	ID string
+
+	proc   *os.Process
+	done   chan struct{}
+	result *SubagentResult
+	mu     sync.Mutex
+}
+
+// Kill terminates the subagent process.
+func (h *SubagentHandle) Kill() error {
+	h.mu.Lock()
+	proc := h.proc
+	h.mu.Unlock()
+	if proc != nil {
+		return proc.Kill()
+	}
+	return nil
+}
+
+// Wait blocks until the subagent completes and returns the result.
+func (h *SubagentHandle) Wait() SubagentResult {
+	<-h.done
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.result != nil {
+		return *h.result
+	}
+	return SubagentResult{Error: fmt.Errorf("subagent completed without result")}
+}
+
+// Done returns a channel that closes when the subagent completes.
+func (h *SubagentHandle) Done() <-chan struct{} {
+	return h.done
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+// subagentJSONOutput matches the JSON envelope produced by `kit --json`.
+type subagentJSONOutput 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"`
+}
+
+var subagentCounter uint64
+
+func generateSubagentID() string {
+	n := atomic.AddUint64(&subagentCounter, 1)
+	return fmt.Sprintf("sub-%d-%d", time.Now().UnixNano(), n)
+}
+
+func findKitBinary() string {
+	// Try the current process executable first.
+	if exe, err := os.Executable(); err == nil {
+		if _, err := os.Stat(exe); err == nil {
+			return exe
+		}
+	}
+	// Fall back to PATH lookup.
+	if p, err := exec.LookPath("kit"); err == nil {
+		return p
+	}
+	return "kit"
+}
+
+// ---------------------------------------------------------------------------
+// SpawnSubagent implementation
+// ---------------------------------------------------------------------------
+
+// SpawnSubagent spawns a child Kit instance to perform a task.
+//
+// When config.Blocking is true, blocks until completion and returns the result
+// directly (handle is nil). When false, returns immediately with a handle for
+// monitoring/cancellation.
+//
+// The subagent runs with --json --no-session --no-extensions flags by default,
+// ensuring isolation from the parent's extensions and session state.
+func SpawnSubagent(cfg SubagentConfig) (*SubagentHandle, *SubagentResult, error) {
+	if cfg.Prompt == "" {
+		return nil, nil, fmt.Errorf("prompt is required")
+	}
+
+	timeout := cfg.Timeout
+	if timeout == 0 {
+		timeout = 5 * time.Minute
+	}
+
+	kitBinary := findKitBinary()
+
+	// Build subprocess arguments.
+	args := []string{
+		"--json",
+		"--no-extensions",
+	}
+	if cfg.NoSession {
+		args = append(args, "--no-session")
+	}
+	if cfg.Model != "" {
+		args = append(args, "--model", cfg.Model)
+	}
+
+	// Handle system prompt - write to temp file if provided.
+	var tmpFile *os.File
+	if cfg.SystemPrompt != "" {
+		var err error
+		tmpFile, err = os.CreateTemp("", "kit-subagent-*.txt")
+		if err != nil {
+			return nil, nil, fmt.Errorf("create temp file: %w", err)
+		}
+		if _, err := tmpFile.WriteString(cfg.SystemPrompt); err != nil {
+			_ = tmpFile.Close()
+			_ = os.Remove(tmpFile.Name())
+			return nil, nil, fmt.Errorf("write system prompt: %w", err)
+		}
+		_ = tmpFile.Close()
+		args = append(args, "--system-prompt", tmpFile.Name())
+	}
+
+	// Add the prompt as a positional argument.
+	args = append(args, cfg.Prompt)
+
+	// Create command with timeout context.
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+
+	cmd := exec.CommandContext(ctx, kitBinary, args...)
+	cmd.Env = os.Environ()
+
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		cancel()
+		if tmpFile != nil {
+			_ = os.Remove(tmpFile.Name())
+		}
+		return nil, nil, fmt.Errorf("stdout pipe: %w", err)
+	}
+	stderr, err := cmd.StderrPipe()
+	if err != nil {
+		cancel()
+		if tmpFile != nil {
+			_ = os.Remove(tmpFile.Name())
+		}
+		return nil, nil, fmt.Errorf("stderr pipe: %w", err)
+	}
+
+	handle := &SubagentHandle{
+		ID:   generateSubagentID(),
+		done: make(chan struct{}),
+	}
+
+	// Start the subprocess.
+	start := time.Now()
+	if err := cmd.Start(); err != nil {
+		cancel()
+		if tmpFile != nil {
+			_ = os.Remove(tmpFile.Name())
+		}
+		return nil, nil, fmt.Errorf("start subprocess: %w", err)
+	}
+
+	handle.mu.Lock()
+	handle.proc = cmd.Process
+	handle.mu.Unlock()
+
+	// Run the subprocess monitoring in a goroutine.
+	go func() {
+		defer close(handle.done)
+		defer cancel()
+		if tmpFile != nil {
+			defer func() { _ = os.Remove(tmpFile.Name()) }()
+		}
+
+		var wg sync.WaitGroup
+		var stdoutBuf strings.Builder
+
+		// Read stderr (live output).
+		wg.Go(func() {
+			scanner := bufio.NewScanner(stderr)
+			scanner.Buffer(make([]byte, 256*1024), 256*1024)
+			for scanner.Scan() {
+				line := scanner.Text()
+				if cfg.OnOutput != nil && strings.TrimSpace(line) != "" {
+					cfg.OnOutput(line + "\n")
+				}
+			}
+		})
+
+		// Read stdout (JSON output).
+		scanner := bufio.NewScanner(stdout)
+		scanner.Buffer(make([]byte, 256*1024), 256*1024)
+		for scanner.Scan() {
+			stdoutBuf.WriteString(scanner.Text() + "\n")
+		}
+
+		wg.Wait()
+		waitErr := cmd.Wait()
+		elapsed := time.Since(start)
+
+		// Build result.
+		result := SubagentResult{Elapsed: elapsed}
+		if waitErr != nil {
+			result.Error = waitErr
+			if exitErr, ok := waitErr.(*exec.ExitError); ok {
+				result.ExitCode = exitErr.ExitCode()
+			} else {
+				result.ExitCode = 1
+			}
+		}
+
+		// Parse JSON output.
+		raw := strings.TrimSpace(stdoutBuf.String())
+		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,
+					OutputTokens: parsed.Usage.OutputTokens,
+				}
+			}
+		} else {
+			// Fallback: use raw stdout.
+			result.Response = raw
+		}
+
+		handle.mu.Lock()
+		handle.result = &result
+		handle.proc = nil
+		handle.mu.Unlock()
+
+		if cfg.OnComplete != nil {
+			cfg.OnComplete(result)
+		}
+	}()
+
+	if cfg.Blocking {
+		// Wait for completion and return result directly.
+		<-handle.done
+		handle.mu.Lock()
+		r := handle.result
+		handle.mu.Unlock()
+		return nil, r, nil
+	}
+
+	return handle, nil, nil
+}

internal/extensions/symbols.go

@@ -110,6 +110,12 @@ func Symbols() interp.Exports {
 			"BeforeCompactEvent":        reflect.ValueOf((*BeforeCompactEvent)(nil)),
 			"BeforeCompactResult":       reflect.ValueOf((*BeforeCompactResult)(nil)),
 
+			// Subagent types
+			"SubagentConfig": reflect.ValueOf((*SubagentConfig)(nil)),
+			"SubagentResult": reflect.ValueOf((*SubagentResult)(nil)),
+			"SubagentUsage":  reflect.ValueOf((*SubagentUsage)(nil)),
+			"SubagentHandle": reflect.ValueOf((*SubagentHandle)(nil)),
+
 			// Event structs
 			"ToolCallEvent":           reflect.ValueOf((*ToolCallEvent)(nil)),
 			"ToolCallResult":          reflect.ValueOf((*ToolCallResult)(nil)),

internal/extensions/wrapper.go

@@ -2,6 +2,7 @@ package extensions
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 
 	"charm.land/fantasy"
@@ -39,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
 // ---------------------------------------------------------------------------
@@ -62,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 {
@@ -82,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.
@@ -90,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 {
@@ -125,10 +164,49 @@ type extensionTool struct {
 }
 
 func (t *extensionTool) Info() fantasy.ToolInfo {
-	return fantasy.ToolInfo{
+	info := fantasy.ToolInfo{
 		Name:        t.def.Name,
 		Description: t.def.Description,
 	}
+
+	// Parse the extension's JSON Schema and extract the properties map.
+	// Fantasy expects Parameters to contain property definitions directly
+	// (e.g. {"command": {"type":"string"}}) and wraps them into a full
+	// JSON Schema object internally. If the extension provides a full
+	// schema with "type":"object" and "properties", we extract just the
+	// properties. Required fields are also extracted if present.
+	if t.def.Parameters != "" {
+		var schema map[string]any
+		if err := json.Unmarshal([]byte(t.def.Parameters), &schema); err == nil {
+			if props, ok := schema["properties"].(map[string]any); ok {
+				info.Parameters = props
+			} else {
+				// Schema doesn't have "properties" — use as-is (may be
+				// a flat property map already matching fantasy's format).
+				info.Parameters = schema
+			}
+			// Extract required fields if present.
+			if req, ok := schema["required"].([]any); ok {
+				for _, r := range req {
+					if s, ok := r.(string); ok {
+						info.Required = append(info.Required, s)
+					}
+				}
+			}
+		}
+	}
+
+	// Ensure Parameters and Required are never nil — the OpenAI Responses API
+	// rejects tools where these fields serialize to JSON null instead of
+	// empty object/array.
+	if info.Parameters == nil {
+		info.Parameters = map[string]any{}
+	}
+	if info.Required == nil {
+		info.Required = []string{}
+	}
+
+	return info
 }
 
 func (t *extensionTool) ProviderOptions() fantasy.ProviderOptions     { return t.providerOptions }

internal/kitsetup/setup.go

@@ -79,6 +79,7 @@ func BuildProviderConfig() (*models.ProviderConfig, string, error) {
 		NumGPU:         &numGPU,
 		MainGPU:        &mainGPU,
 		TLSSkipVerify:  viper.GetBool("tls-skip-verify"),
+		ThinkingLevel:  models.ParseThinkingLevel(viper.GetString("thinking-level")),
 	}
 
 	return cfg, systemPrompt, nil

internal/message/content.go

@@ -58,6 +58,16 @@ type ToolResult struct {
 
 func (ToolResult) isPart() {}
 
+// ImageContent holds image data within a message. The data is stored as raw
+// bytes (not base64-encoded); serialization handles encoding. MediaType is a
+// MIME type such as "image/png" or "image/jpeg".
+type ImageContent struct {
+	Data      []byte `json:"data"`
+	MediaType string `json:"media_type"`
+}
+
+func (ImageContent) isPart() {}
+
 // Finish marks the end of an assistant turn, carrying the stop reason.
 type Finish struct {
 	Reason string `json:"reason"` // "end_turn", "tool_use", "max_tokens", etc.
@@ -129,6 +139,17 @@ func (m *Message) ToolResults() []ToolResult {
 	return results
 }
 
+// Images returns all ImageContent parts from this message.
+func (m *Message) Images() []ImageContent {
+	var images []ImageContent
+	for _, part := range m.Parts {
+		if ic, ok := part.(ImageContent); ok {
+			images = append(images, ic)
+		}
+	}
+	return images
+}
+
 // Reasoning returns the ReasoningContent if present, or a zero value.
 func (m *Message) Reasoning() ReasoningContent {
 	for _, part := range m.Parts {
@@ -170,6 +191,7 @@ const (
 	toolCallType   partType = "tool_call"
 	toolResultType partType = "tool_result"
 	finishType     partType = "finish"
+	imageType      partType = "image"
 )
 
 type partWrapper struct {
@@ -194,6 +216,8 @@ func MarshalParts(parts []ContentPart) ([]byte, error) {
 			pt = toolResultType
 		case Finish:
 			pt = finishType
+		case ImageContent:
+			pt = imageType
 		default:
 			return nil, fmt.Errorf("unknown content part type: %T", part)
 		}
@@ -247,6 +271,12 @@ func UnmarshalParts(data []byte) ([]ContentPart, error) {
 				return nil, fmt.Errorf("failed to unmarshal finish part: %w", err)
 			}
 			part = p
+		case imageType:
+			var p ImageContent
+			if err := json.Unmarshal(w.Data, &p); err != nil {
+				return nil, fmt.Errorf("failed to unmarshal image part: %w", err)
+			}
+			part = p
 		default:
 			return nil, fmt.Errorf("unknown part type: %s", w.Type)
 		}
@@ -323,13 +353,25 @@ func (m *Message) ToFantasyMessages() []fantasy.Message {
 		}}
 
 	case RoleUser:
+		var parts []fantasy.MessagePart
 		text := m.Content()
-		if text == "" {
+		if text != "" {
+			parts = append(parts, fantasy.TextPart{Text: text})
+		}
+		for _, part := range m.Parts {
+			if ic, ok := part.(ImageContent); ok {
+				parts = append(parts, fantasy.FilePart{
+					Data:      ic.Data,
+					MediaType: ic.MediaType,
+				})
+			}
+		}
+		if len(parts) == 0 {
 			return nil
 		}
 		return []fantasy.Message{{
 			Role:    fantasy.MessageRoleUser,
-			Content: []fantasy.MessagePart{fantasy.TextPart{Text: text}},
+			Content: parts,
 		}}
 
 	case RoleSystem:
@@ -388,6 +430,13 @@ func FromFantasyMessage(msg fantasy.Message) Message {
 					Thinking: p.Text,
 				})
 			}
+		case fantasy.FilePart:
+			if len(p.Data) > 0 {
+				m.Parts = append(m.Parts, ImageContent{
+					Data:      p.Data,
+					MediaType: p.MediaType,
+				})
+			}
 		}
 	}
 

internal/models/pool.go

@@ -0,0 +1,193 @@
+package models
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"charm.land/fantasy"
+)
+
+// ProviderPool manages reusable LLM provider instances to reduce overhead
+// when spawning multiple subagents or making repeated completion calls.
+type ProviderPool struct {
+	mu        sync.RWMutex
+	providers map[string]*pooledProvider
+	ttl       time.Duration
+	closed    bool
+	closeCh   chan struct{}
+}
+
+type pooledProvider struct {
+	model        fantasy.LanguageModel
+	closer       func() error
+	providerOpts fantasy.ProviderOptions
+	created      time.Time
+	lastUsed     time.Time
+	refs         int32
+}
+
+// DefaultPoolTTL is the default time-to-live for idle pooled providers.
+const DefaultPoolTTL = 5 * time.Minute
+
+// globalPool is the singleton provider pool instance.
+var globalPool *ProviderPool
+var poolOnce sync.Once
+
+// GetGlobalPool returns the singleton provider pool instance.
+func GetGlobalPool() *ProviderPool {
+	poolOnce.Do(func() {
+		globalPool = NewProviderPool(DefaultPoolTTL)
+	})
+	return globalPool
+}
+
+// NewProviderPool creates a provider pool with the given TTL for idle providers.
+func NewProviderPool(ttl time.Duration) *ProviderPool {
+	p := &ProviderPool{
+		providers: make(map[string]*pooledProvider),
+		ttl:       ttl,
+		closeCh:   make(chan struct{}),
+	}
+	go p.cleanupLoop()
+	return p
+}
+
+// Get returns a provider for the model string, creating one if needed.
+// The returned release function must be called when the provider is no longer
+// needed. The provider may be reused by subsequent Get calls.
+func (p *ProviderPool) Get(ctx context.Context, modelString string) (fantasy.LanguageModel, fantasy.ProviderOptions, func(), error) {
+	p.mu.Lock()
+
+	// Check if we have an existing provider.
+	if pp, ok := p.providers[modelString]; ok {
+		pp.refs++
+		pp.lastUsed = time.Now()
+		p.mu.Unlock()
+		return pp.model, pp.providerOpts, func() { p.release(modelString) }, nil
+	}
+
+	p.mu.Unlock()
+
+	// Create a new provider outside the lock.
+	config := &ProviderConfig{ModelString: modelString}
+	result, err := CreateProvider(ctx, config)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	// Double-check: another goroutine may have created one while we were unlocked.
+	if pp, ok := p.providers[modelString]; ok {
+		// Close the one we just created and use the existing one.
+		if result.Closer != nil {
+			_ = result.Closer.Close()
+		}
+		pp.refs++
+		pp.lastUsed = time.Now()
+		return pp.model, pp.providerOpts, func() { p.release(modelString) }, nil
+	}
+
+	var closerFn func() error
+	if result.Closer != nil {
+		closerFn = result.Closer.Close
+	}
+
+	pp := &pooledProvider{
+		model:        result.Model,
+		closer:       closerFn,
+		providerOpts: result.ProviderOptions,
+		created:      time.Now(),
+		lastUsed:     time.Now(),
+		refs:         1,
+	}
+	p.providers[modelString] = pp
+
+	return pp.model, pp.providerOpts, func() { p.release(modelString) }, nil
+}
+
+func (p *ProviderPool) release(modelString string) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if pp, ok := p.providers[modelString]; ok {
+		pp.refs--
+		pp.lastUsed = time.Now()
+	}
+}
+
+func (p *ProviderPool) cleanupLoop() {
+	ticker := time.NewTicker(p.ttl / 2)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-p.closeCh:
+			return
+		case <-ticker.C:
+			p.cleanup()
+		}
+	}
+}
+
+func (p *ProviderPool) cleanup() {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	now := time.Now()
+	for key, pp := range p.providers {
+		// Only clean up providers with no active references and past TTL.
+		if pp.refs <= 0 && now.Sub(pp.lastUsed) > p.ttl {
+			if pp.closer != nil {
+				_ = pp.closer()
+			}
+			delete(p.providers, key)
+		}
+	}
+}
+
+// Close shuts down the pool and releases all providers.
+func (p *ProviderPool) Close() {
+	p.mu.Lock()
+	if p.closed {
+		p.mu.Unlock()
+		return
+	}
+	p.closed = true
+	close(p.closeCh)
+
+	for key, pp := range p.providers {
+		if pp.closer != nil {
+			_ = pp.closer()
+		}
+		delete(p.providers, key)
+	}
+	p.mu.Unlock()
+}
+
+// Stats returns current pool statistics.
+func (p *ProviderPool) Stats() PoolStats {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+
+	stats := PoolStats{
+		TotalProviders: len(p.providers),
+	}
+	for _, pp := range p.providers {
+		if pp.refs > 0 {
+			stats.ActiveProviders++
+		} else {
+			stats.IdleProviders++
+		}
+	}
+	return stats
+}
+
+// PoolStats contains provider pool statistics.
+type PoolStats struct {
+	TotalProviders  int
+	ActiveProviders int
+	IdleProviders   int
+}

internal/models/providers.go

@@ -57,6 +57,66 @@ func resolveModelAlias(provider, modelName string) string {
 	return modelName
 }
 
+// ThinkingLevel controls extended thinking / reasoning budget for supported models.
+type ThinkingLevel string
+
+const (
+	ThinkingOff     ThinkingLevel = "off"
+	ThinkingMinimal ThinkingLevel = "minimal"
+	ThinkingLow     ThinkingLevel = "low"
+	ThinkingMedium  ThinkingLevel = "medium"
+	ThinkingHigh    ThinkingLevel = "high"
+)
+
+// ThinkingLevels returns the ordered list of available thinking levels for cycling.
+func ThinkingLevels() []ThinkingLevel {
+	return []ThinkingLevel{ThinkingOff, ThinkingMinimal, ThinkingLow, ThinkingMedium, ThinkingHigh}
+}
+
+// ThinkingBudgetTokens returns the token budget for a thinking level, or 0 for "off".
+func ThinkingBudgetTokens(level ThinkingLevel) int64 {
+	switch level {
+	case ThinkingMinimal:
+		return 1024
+	case ThinkingLow:
+		return 4096
+	case ThinkingMedium:
+		return 10240
+	case ThinkingHigh:
+		return 20480
+	default:
+		return 0
+	}
+}
+
+// ThinkingLevelDescription returns a human-readable description of a thinking level.
+func ThinkingLevelDescription(level ThinkingLevel) string {
+	switch level {
+	case ThinkingOff:
+		return "No reasoning"
+	case ThinkingMinimal:
+		return "Very brief reasoning (~1k tokens)"
+	case ThinkingLow:
+		return "Light reasoning (~4k tokens)"
+	case ThinkingMedium:
+		return "Moderate reasoning (~10k tokens)"
+	case ThinkingHigh:
+		return "Deep reasoning (~20k tokens)"
+	default:
+		return "No reasoning"
+	}
+}
+
+// ParseThinkingLevel converts a string to a ThinkingLevel, defaulting to ThinkingOff.
+func ParseThinkingLevel(s string) ThinkingLevel {
+	switch ThinkingLevel(s) {
+	case ThinkingMinimal, ThinkingLow, ThinkingMedium, ThinkingHigh:
+		return ThinkingLevel(s)
+	default:
+		return ThinkingOff
+	}
+}
+
 // ProviderConfig holds configuration for creating LLM providers.
 type ProviderConfig struct {
 	ModelString    string
@@ -71,6 +131,7 @@ type ProviderConfig struct {
 	NumGPU         *int32
 	MainGPU        *int32
 	TLSSkipVerify  bool
+	ThinkingLevel  ThinkingLevel
 }
 
 // ProviderResult contains the result of provider creation.
@@ -82,6 +143,9 @@ type ProviderResult struct {
 	// Closer is an optional cleanup function for providers that hold
 	// resources (e.g. kronk's loaded models). May be nil.
 	Closer io.Closer
+	// ProviderOptions contains provider-specific options to be passed to the
+	// fantasy agent (e.g. OpenAI Responses API reasoning options).
+	ProviderOptions fantasy.ProviderOptions
 }
 
 // ParseModelString parses a model string in "provider/model" format (e.g. "anthropic/claude-sonnet-4-5").
@@ -146,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 {
@@ -256,6 +321,8 @@ func createAutoRoutedOpenAICompatProvider(ctx context.Context, config *ProviderC
 // createAutoRoutedAnthropicProvider creates an anthropic provider for
 // third-party providers with anthropic-compatible APIs (e.g. minimax).
 func createAutoRoutedAnthropicProvider(ctx context.Context, config *ProviderConfig, modelName string, info *ProviderInfo) (*ProviderResult, error) {
+	clearConflictingAnthropicSamplingParams(config)
+
 	apiKey := resolveAPIKey(config.ProviderAPIKey, info.Env)
 	if apiKey == "" {
 		return nil, fmt.Errorf("%s API key not provided. Use --provider-api-key or set %s",
@@ -297,6 +364,7 @@ func createAutoRoutedOpenAIProvider(ctx context.Context, config *ProviderConfig,
 
 	var opts []openai.Option
 	opts = append(opts, openai.WithAPIKey(apiKey))
+	opts = append(opts, openai.WithUseResponsesAPI())
 
 	if config.ProviderURL != "" {
 		opts = append(opts, openai.WithBaseURL(config.ProviderURL))
@@ -316,7 +384,9 @@ func createAutoRoutedOpenAIProvider(ctx context.Context, config *ProviderConfig,
 		return nil, fmt.Errorf("failed to create %s model: %w", info.Name, err)
 	}
 
-	return &ProviderResult{Model: model}, nil
+	providerOpts := buildOpenAIProviderOptions(config, modelName)
+
+	return &ProviderResult{Model: model, ProviderOptions: providerOpts}, nil
 }
 
 // resolveAPIKey returns the first non-empty API key from the explicit key
@@ -347,7 +417,102 @@ func validateModelConfig(config *ProviderConfig, modelInfo *ModelInfo) {
 	}
 }
 
+// clearConflictingAnthropicSamplingParams ensures that temperature and top_p are
+// not both sent to the Anthropic API, which rejects requests containing both.
+// When both are set (typically from defaults), top_p is cleared so that
+// temperature takes precedence.
+func clearConflictingAnthropicSamplingParams(config *ProviderConfig) {
+	if config.Temperature != nil && config.TopP != nil {
+		config.TopP = nil
+	}
+}
+
+// buildOpenAIProviderOptions returns fantasy.ProviderOptions configured for
+// OpenAI Responses API models. For reasoning models it sets reasoning_summary
+// to "auto", includes encrypted reasoning content, and maps the ThinkingLevel
+// to an OpenAI ReasoningEffort. For non-responses or non-reasoning models the
+// returned map is nil (no extra options needed).
+func buildOpenAIProviderOptions(config *ProviderConfig, modelName string) fantasy.ProviderOptions {
+	if !openai.IsResponsesModel(modelName) {
+		return nil
+	}
+
+	if openai.IsResponsesReasoningModel(modelName) {
+		reasoningSummary := "auto"
+		opts := &openai.ResponsesProviderOptions{
+			ReasoningSummary: &reasoningSummary,
+			Include: []openai.IncludeType{
+				openai.IncludeReasoningEncryptedContent,
+			},
+		}
+
+		// Map ThinkingLevel to OpenAI ReasoningEffort.
+		if effort := thinkingLevelToReasoningEffort(config.ThinkingLevel); effort != nil {
+			opts.ReasoningEffort = effort
+		}
+
+		return fantasy.ProviderOptions{
+			openai.Name: opts,
+		}
+	}
+
+	return nil
+}
+
+// thinkingLevelToReasoningEffort maps a ThinkingLevel to an OpenAI ReasoningEffort.
+// Returns nil for ThinkingOff (use the model's default).
+func thinkingLevelToReasoningEffort(level ThinkingLevel) *openai.ReasoningEffort {
+	switch level {
+	case ThinkingMinimal:
+		return openai.ReasoningEffortOption(openai.ReasoningEffortMinimal)
+	case ThinkingLow:
+		return openai.ReasoningEffortOption(openai.ReasoningEffortLow)
+	case ThinkingMedium:
+		return openai.ReasoningEffortOption(openai.ReasoningEffortMedium)
+	case ThinkingHigh:
+		return openai.ReasoningEffortOption(openai.ReasoningEffortHigh)
+	default:
+		return nil
+	}
+}
+
+// buildAnthropicProviderOptions returns fantasy.ProviderOptions configured for
+// Anthropic models with extended thinking. When thinking is enabled, it sets
+// SendReasoning to true and configures the thinking budget. For thinking-off
+// or non-reasoning models the returned map is nil.
+//
+// Anthropic requires max_tokens > thinking.budget_tokens. If the configured
+// MaxTokens is too low, it is bumped to budget + 4096 to leave room for the
+// actual response.
+func buildAnthropicProviderOptions(config *ProviderConfig, modelName string) fantasy.ProviderOptions {
+	if config.ThinkingLevel == "" || config.ThinkingLevel == ThinkingOff {
+		return nil
+	}
+
+	budget := ThinkingBudgetTokens(config.ThinkingLevel)
+	if budget == 0 {
+		return nil
+	}
+
+	// Ensure MaxTokens exceeds the thinking budget (Anthropic requirement).
+	minRequired := int(budget) + 4096
+	if config.MaxTokens < minRequired {
+		config.MaxTokens = minRequired
+	}
+
+	sendReasoning := true
+	opts := &anthropic.ProviderOptions{
+		SendReasoning: &sendReasoning,
+		Thinking: &anthropic.ThinkingProviderOption{
+			BudgetTokens: budget,
+		},
+	}
+	return anthropic.NewProviderOptions(opts)
+}
+
 func createAnthropicProvider(ctx context.Context, config *ProviderConfig, modelName string) (*ProviderResult, error) {
+	clearConflictingAnthropicSamplingParams(config)
+
 	apiKey, source, err := auth.GetAnthropicAPIKey(config.ProviderAPIKey)
 	if err != nil {
 		return nil, err
@@ -383,10 +548,15 @@ func createAnthropicProvider(ctx context.Context, config *ProviderConfig, modelN
 		return nil, fmt.Errorf("failed to create Anthropic model: %w", err)
 	}
 
-	return &ProviderResult{Model: model}, nil
+	// Build provider options for extended thinking (reasoning budget).
+	providerOpts := buildAnthropicProviderOptions(config, modelName)
+
+	return &ProviderResult{Model: model, ProviderOptions: providerOpts}, nil
 }
 
 func createVertexAnthropicProvider(ctx context.Context, config *ProviderConfig, modelName string) (*ProviderResult, error) {
+	clearConflictingAnthropicSamplingParams(config)
+
 	projectID := firstNonEmpty(
 		os.Getenv("GOOGLE_VERTEX_PROJECT"),
 		os.Getenv("ANTHROPIC_VERTEX_PROJECT_ID"),
@@ -434,6 +604,7 @@ func createOpenAIProvider(ctx context.Context, config *ProviderConfig, modelName
 
 	var opts []openai.Option
 	opts = append(opts, openai.WithAPIKey(apiKey))
+	opts = append(opts, openai.WithUseResponsesAPI())
 
 	if config.ProviderURL != "" {
 		opts = append(opts, openai.WithBaseURL(config.ProviderURL))
@@ -453,7 +624,10 @@ func createOpenAIProvider(ctx context.Context, config *ProviderConfig, modelName
 		return nil, fmt.Errorf("failed to create OpenAI model: %w", err)
 	}
 
-	return &ProviderResult{Model: model}, nil
+	// Build provider options for OpenAI Responses API reasoning models.
+	providerOpts := buildOpenAIProviderOptions(config, modelName)
+
+	return &ProviderResult{Model: model, ProviderOptions: providerOpts}, nil
 }
 
 func createGoogleProvider(ctx context.Context, config *ProviderConfig, modelName string) (*ProviderResult, error) {
@@ -869,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/session/entry.go

@@ -38,6 +38,10 @@ type SessionHeader struct {
 	Timestamp     time.Time `json:"timestamp"`                // creation time
 	Cwd           string    `json:"cwd"`                      // working directory
 	ParentSession string    `json:"parent_session,omitempty"` // path to parent if forked
+
+	// Subagent fields (set when session is created by a subagent)
+	ParentSessionID string `json:"parent_session_id,omitempty"` // UUID of parent session
+	SubagentTask    string `json:"subagent_task,omitempty"`     // original task prompt
 }
 
 // Entry is the common structure shared by all tree entries (everything except

internal/session/store.go

@@ -29,6 +29,12 @@ type SessionInfo struct {
 	// ParentSessionPath is the parent session path if this session was forked.
 	ParentSessionPath string
 
+	// ParentSessionID is the UUID of the parent session (for subagent sessions).
+	ParentSessionID string
+
+	// SubagentTask is the original task prompt (for subagent sessions).
+	SubagentTask string
+
 	// Created is when the session was first created.
 	Created time.Time
 
@@ -162,6 +168,8 @@ func extractSessionInfo(path string) (*SessionInfo, error) {
 			info.Created = h.Timestamp
 			info.Modified = h.Timestamp
 			info.ParentSessionPath = h.ParentSession
+			info.ParentSessionID = h.ParentSessionID
+			info.SubagentTask = h.SubagentTask
 			continue
 		}
 
@@ -245,3 +253,27 @@ func extractTextPreview(partsJSON json.RawMessage) string {
 func DeleteSession(path string) error {
 	return os.Remove(path)
 }
+
+// ListChildSessions returns all sessions that have the given session ID as
+// their parent. This is useful for finding subagent sessions spawned from
+// a parent session. Results are sorted by creation time (newest first).
+func ListChildSessions(parentID string) ([]SessionInfo, error) {
+	if parentID == "" {
+		return nil, nil
+	}
+
+	allSessions, err := ListAllSessions()
+	if err != nil {
+		return nil, err
+	}
+
+	var children []SessionInfo
+	for _, s := range allSessions {
+		if s.ParentSessionID == parentID {
+			children = append(children, s)
+		}
+	}
+
+	// Already sorted by modification time from ListAllSessions
+	return children, nil
+}

internal/ui/children_test.go

@@ -348,6 +348,9 @@ func TestStreamComponent_SpinnerKeepsRunningDuringStreaming(t *testing.T) {
 	// Receive first chunk — spinner should keep running.
 	c = sendStreamMsg(c, app.StreamChunkEvent{Content: "hello"})
 
+	// Flush pending chunks (simulates the 16ms tick firing).
+	c = sendStreamMsg(c, streamFlushTickMsg{})
+
 	if !c.spinning {
 		t.Fatal("expected spinning=true after first chunk")
 	}
@@ -372,6 +375,9 @@ func TestStreamComponent_ChunkAccumulation(t *testing.T) {
 		c = sendStreamMsg(c, app.StreamChunkEvent{Content: chunk})
 	}
 
+	// Flush pending chunks (simulates the 16ms tick firing).
+	c = sendStreamMsg(c, streamFlushTickMsg{})
+
 	got := c.streamContent.String()
 	want := "Hello, world!"
 	if got != want {
@@ -397,8 +403,8 @@ func TestStreamComponent_ToolExecution_IsStarting_ShowsSpinner(t *testing.T) {
 	if !c.spinning {
 		t.Fatal("expected spinning=true during tool execution")
 	}
-	if !strings.Contains(c.spinnerMsg, "exec_tool") {
-		t.Fatalf("expected spinnerMsg to contain tool name, got %q", c.spinnerMsg)
+	if len(c.activeTools) != 1 || !strings.Contains(c.activeTools[0], "exec_tool") {
+		t.Fatalf("expected activeTools to contain tool name, got %v", c.activeTools)
 	}
 	if cmd == nil {
 		t.Fatal("expected tick cmd from ToolExecutionEvent{IsStarting:true}")
@@ -410,7 +416,11 @@ func TestStreamComponent_ToolExecution_NotStarting_KeepsSpinning(t *testing.T) {
 	c := newTestStream()
 	// Start spinning first (simulating execution in progress).
 	c = sendStreamMsg(c, app.SpinnerEvent{Show: true})
-	c.spinnerMsg = "Executing some_tool…"
+	// Simulate a tool starting
+	c = sendStreamMsg(c, app.ToolExecutionEvent{
+		ToolName:   "some_tool",
+		IsStarting: true,
+	})
 
 	c = sendStreamMsg(c, app.ToolExecutionEvent{
 		ToolName:   "some_tool",
@@ -420,8 +430,41 @@ func TestStreamComponent_ToolExecution_NotStarting_KeepsSpinning(t *testing.T) {
 	if !c.spinning {
 		t.Fatal("expected spinning=true after tool execution finished (spinner keeps running)")
 	}
-	if c.spinnerMsg != "" {
-		t.Fatalf("expected spinnerMsg cleared after tool finished, got %q", c.spinnerMsg)
+	if len(c.activeTools) != 0 {
+		t.Fatalf("expected activeTools cleared after tool finished, got %v", c.activeTools)
+	}
+}
+
+// TestStreamComponent_ParallelToolExecution verifies multiple tools can run concurrently.
+func TestStreamComponent_ParallelToolExecution(t *testing.T) {
+	c := newTestStream()
+
+	// Start three tools in parallel
+	c = sendStreamMsg(c, app.ToolExecutionEvent{ToolName: "read", IsStarting: true})
+	c = sendStreamMsg(c, app.ToolExecutionEvent{ToolName: "grep", IsStarting: true})
+	c = sendStreamMsg(c, app.ToolExecutionEvent{ToolName: "find", IsStarting: true})
+
+	if len(c.activeTools) != 3 {
+		t.Fatalf("expected 3 active tools, got %d: %v", len(c.activeTools), c.activeTools)
+	}
+
+	// Check SpinnerView shows all tools
+	view := c.SpinnerView()
+	if !strings.Contains(view, "Running:") {
+		t.Fatalf("expected spinner view to contain 'Running:' for multiple tools, got %q", view)
+	}
+
+	// Finish one tool
+	c = sendStreamMsg(c, app.ToolExecutionEvent{ToolName: "grep", IsStarting: false})
+	if len(c.activeTools) != 2 {
+		t.Fatalf("expected 2 active tools after one finished, got %d: %v", len(c.activeTools), c.activeTools)
+	}
+
+	// Finish remaining tools
+	c = sendStreamMsg(c, app.ToolExecutionEvent{ToolName: "read", IsStarting: false})
+	c = sendStreamMsg(c, app.ToolExecutionEvent{ToolName: "find", IsStarting: false})
+	if len(c.activeTools) != 0 {
+		t.Fatalf("expected 0 active tools after all finished, got %d: %v", len(c.activeTools), c.activeTools)
 	}
 }
 
@@ -480,8 +523,8 @@ func TestStreamComponent_Reset(t *testing.T) {
 	if !c.timestamp.IsZero() {
 		t.Fatal("expected zero timestamp after Reset()")
 	}
-	if c.spinnerMsg != "" {
-		t.Fatalf("expected spinnerMsg empty after Reset(), got %q", c.spinnerMsg)
+	if len(c.activeTools) != 0 {
+		t.Fatalf("expected activeTools empty after Reset(), got %v", c.activeTools)
 	}
 }
 

internal/ui/commands.go

@@ -1,6 +1,11 @@
 package ui
 
-import "slices"
+import (
+	"slices"
+	"strings"
+
+	"github.com/mark3labs/kit/internal/models"
+)
 
 // SlashCommand represents a user-invokable slash command with its metadata.
 // Commands can have multiple aliases and are organized by category for better
@@ -66,6 +71,29 @@ var SlashCommands = []SlashCommand{
 		Category:    "System",
 		Aliases:     []string{"/co"},
 	},
+	{
+		Name:        "/model",
+		Description: "Switch to a different model",
+		Category:    "System",
+		Aliases:     []string{"/m"},
+	},
+	{
+		Name:        "/thinking",
+		Description: "Set thinking/reasoning level (off, minimal, low, medium, high)",
+		Category:    "System",
+		Aliases:     []string{"/think"},
+		Complete: func(prefix string) []string {
+			levels := models.ThinkingLevels()
+			var matches []string
+			for _, l := range levels {
+				s := string(l)
+				if prefix == "" || strings.HasPrefix(s, strings.ToLower(prefix)) {
+					matches = append(matches, s)
+				}
+			}
+			return matches
+		},
+	},
 	{
 		Name:        "/quit",
 		Description: "Exit the application",

internal/ui/events.go

@@ -1,10 +1,23 @@
 package ui
 
+// ImageAttachment holds a clipboard image that will be sent alongside the
+// user's text prompt to the LLM. The data is raw image bytes; MediaType is
+// a MIME type like "image/png".
+type ImageAttachment struct {
+	// Data is the raw image bytes (PNG, JPEG, etc.).
+	Data []byte
+	// MediaType is the MIME type (e.g. "image/png", "image/jpeg").
+	MediaType string
+}
+
 // submitMsg is sent by the InputComponent when the user submits a text prompt.
 // The parent model receives this and calls app.Run(Text) to start agent processing.
 type submitMsg struct {
 	// Text is the user's input text to send to the agent.
 	Text string
+	// Images holds clipboard image attachments to send alongside the text.
+	// Empty when no images are attached.
+	Images []ImageAttachment
 }
 
 // cancelTimerExpiredMsg is sent by the tea.Tick command that starts when the user
@@ -28,3 +41,33 @@ type TreeNodeSelectedMsg struct {
 
 // TreeCancelledMsg is sent when the user cancels the tree selector (ESC).
 type TreeCancelledMsg struct{}
+
+// shellCommandMsg is sent by the InputComponent when the user submits a
+// ! or !! prefixed command. The parent model intercepts this to execute
+// the shell command directly instead of forwarding to the LLM.
+//
+// Matching pi's behavior:
+//   - !cmd  → run shell command, output INCLUDED in LLM context
+//   - !!cmd → run shell command, output EXCLUDED from LLM context
+type shellCommandMsg struct {
+	// Command is the shell command to execute (prefix stripped).
+	Command string
+	// ExcludeFromContext is true for !! (output excluded from LLM context),
+	// false for ! (output included in LLM context).
+	ExcludeFromContext bool
+}
+
+// shellCommandResultMsg carries the result of a shell command execution
+// back to the parent model for display.
+type shellCommandResultMsg struct {
+	// Command is the original shell command that was executed.
+	Command string
+	// Output is the combined stdout/stderr output.
+	Output string
+	// ExitCode is the process exit code (0 = success).
+	ExitCode int
+	// Err is non-nil if the command failed to start or timed out.
+	Err error
+	// ExcludeFromContext mirrors the flag from shellCommandMsg.
+	ExcludeFromContext bool
+}

internal/ui/file_processor.go

@@ -0,0 +1,129 @@
+package ui
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// fileTokenPattern matches @file references in user text. Supports:
+//   - @"path with spaces.txt" (quoted)
+//   - @path/to/file.txt      (unquoted, no spaces)
+var fileTokenPattern = regexp.MustCompile(`@"[^"]+"|@[^\s]+`)
+
+// ProcessFileAttachments scans the user's input text for @file references,
+// reads each referenced file, and returns the text with @tokens replaced by
+// XML-wrapped file content. Non-file @ tokens (like email addresses) are left
+// unchanged.
+//
+// Returns the original text unchanged if no valid @file references are found.
+func ProcessFileAttachments(text string, cwd string) string {
+	tokens := fileTokenPattern.FindAllString(text, -1)
+	if len(tokens) == 0 {
+		return text
+	}
+
+	result := text
+	for _, token := range tokens {
+		path := tokenToPath(token)
+		if path == "" {
+			continue
+		}
+
+		absPath, err := resolvePath(path, cwd)
+		if err != nil {
+			// Not a valid file reference — leave the token as-is.
+			// This handles cases like email addresses (@user) gracefully.
+			continue
+		}
+
+		info, err := os.Stat(absPath)
+		if err != nil {
+			continue
+		}
+
+		// Skip directories — we only attach file content.
+		if info.IsDir() {
+			continue
+		}
+
+		// Skip empty files.
+		if info.Size() == 0 {
+			continue
+		}
+
+		content, err := os.ReadFile(absPath)
+		if err != nil {
+			continue
+		}
+
+		// Build the XML-wrapped replacement.
+		wrapped := wrapFileContent(absPath, content)
+		result = strings.Replace(result, token, wrapped, 1)
+	}
+
+	return result
+}
+
+// tokenToPath strips the @ prefix and optional quotes from a token,
+// returning the raw file path. Returns "" for invalid tokens.
+func tokenToPath(token string) string {
+	if !strings.HasPrefix(token, "@") {
+		return ""
+	}
+	path := token[1:]
+
+	// Strip quotes.
+	if strings.HasPrefix(path, `"`) && strings.HasSuffix(path, `"`) {
+		path = path[1 : len(path)-1]
+	}
+
+	// Reject obviously non-file tokens (e.g. bare @ or @-flags).
+	if path == "" || strings.HasPrefix(path, "-") {
+		return ""
+	}
+
+	return path
+}
+
+// resolvePath resolves a potentially relative file path to an absolute path.
+// Supports ~/ expansion and relative paths. No CWD restriction — the user
+// can reference any file they have read access to.
+func resolvePath(path string, cwd string) (string, error) {
+	// Expand ~/
+	if strings.HasPrefix(path, "~/") {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("cannot expand ~: %w", err)
+		}
+		path = filepath.Join(home, path[2:])
+	}
+
+	// Resolve relative to cwd.
+	if !filepath.IsAbs(path) {
+		path = filepath.Join(cwd, path)
+	}
+
+	// Clean and resolve symlinks for consistent paths.
+	absPath, err := filepath.Abs(path)
+	if err != nil {
+		return "", fmt.Errorf("invalid path: %w", err)
+	}
+
+	// Resolve symlinks so the displayed path is canonical.
+	resolved, err := filepath.EvalSymlinks(absPath)
+	if err != nil {
+		// EvalSymlinks fails if the file doesn't exist — fall back to
+		// the cleaned absolute path and let the caller's Stat handle it.
+		return absPath, nil
+	}
+
+	return resolved, nil
+}
+
+// wrapFileContent wraps file content in XML tags for LLM consumption.
+func wrapFileContent(absPath string, content []byte) string {
+	return fmt.Sprintf("<file path=\"%s\">\n%s\n</file>", absPath, string(content))
+}

internal/ui/file_suggestions.go

@@ -0,0 +1,388 @@
+package ui
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"unicode/utf8"
+)
+
+// FileSuggestion represents a single file or directory suggestion for the @
+// autocomplete popup.
+type FileSuggestion struct {
+	// RelPath is the path relative to the search base (e.g. "cmd/kit/main.go").
+	RelPath string
+	// IsDir is true when the entry is a directory.
+	IsDir bool
+	// Score is the fuzzy match score (higher is better).
+	Score int
+}
+
+// maxFileSuggestions is the maximum number of file suggestions returned.
+const maxFileSuggestions = 20
+
+// ExtractAtPrefix checks the current line for an @-file trigger at cursorCol.
+// It returns:
+//   - hasAt: true if a valid @ trigger was found
+//   - prefix: the text after @ (possibly empty) that the user has typed so far
+//   - startIdx: byte offset of the @ character in the line
+//
+// The @ must appear at the start of the line or after whitespace. Quoted paths
+// are supported: @"path with spaces" — the returned prefix strips quotes.
+func ExtractAtPrefix(line string, cursorCol int) (hasAt bool, prefix string, startIdx int) {
+	if cursorCol > len(line) {
+		cursorCol = len(line)
+	}
+
+	// Walk backwards from cursorCol to find the @ character.
+	text := line[:cursorCol]
+
+	// Find the last @ that is preceded by whitespace or is at position 0.
+	atIdx := -1
+	for i := len(text) - 1; i >= 0; i-- {
+		if text[i] == '@' {
+			// Must be at start of line or preceded by whitespace.
+			if i == 0 || text[i-1] == ' ' || text[i-1] == '\t' {
+				atIdx = i
+				break
+			}
+		}
+		// Stop scanning if we hit a space — the @ we want must be in the
+		// current "word".
+		if text[i] == ' ' || text[i] == '\t' {
+			break
+		}
+	}
+
+	if atIdx < 0 {
+		return false, "", 0
+	}
+
+	raw := text[atIdx+1:]
+
+	// Handle quoted paths: @"some path" — strip leading quote.
+	if after, found := strings.CutPrefix(raw, `"`); found {
+		raw = strings.TrimSuffix(after, `"`)
+	}
+
+	return true, raw, atIdx
+}
+
+// GetFileSuggestions returns file/directory suggestions matching the given
+// prefix. It tries `git ls-files` first (fast, respects .gitignore), then
+// falls back to a simple directory walk.
+//
+// If prefix contains a path separator the search is scoped to that
+// subdirectory. For example, prefix "cmd/k" searches inside "cmd/" for
+// entries matching "k".
+func GetFileSuggestions(prefix string, cwd string) []FileSuggestion {
+	// Resolve the base directory and filter query from the prefix.
+	baseDir, query := splitPrefixPath(prefix)
+
+	searchDir := cwd
+	if baseDir != "" {
+		candidate := resolveSearchDir(baseDir, cwd)
+		if info, err := os.Stat(candidate); err == nil && info.IsDir() {
+			searchDir = candidate
+		} else {
+			return nil // invalid base directory
+		}
+	}
+
+	files := listFiles(searchDir, cwd)
+	if len(files) == 0 {
+		return nil
+	}
+
+	// Prepend baseDir so results display as "cmd/main.go" not just "main.go".
+	if baseDir != "" {
+		for i := range files {
+			files[i].RelPath = baseDir + files[i].RelPath
+		}
+	}
+
+	return fuzzyFilterFiles(files, prefix, query)
+}
+
+// splitPrefixPath separates a prefix like "cmd/kit/m" into
+// baseDir="cmd/kit/" and query="m". If there is no separator the
+// baseDir is empty and query is the full prefix.
+func splitPrefixPath(prefix string) (baseDir, query string) {
+	// Handle ~ expansion display (we keep it in the prefix for display
+	// but resolve it when actually searching).
+	idx := strings.LastIndex(prefix, "/")
+	if idx < 0 {
+		return "", prefix
+	}
+	return prefix[:idx+1], prefix[idx+1:]
+}
+
+// resolveSearchDir converts a baseDir from the prefix into an absolute path.
+// Supports ~/, ../, and absolute paths.
+func resolveSearchDir(baseDir, cwd string) string {
+	// Expand ~/
+	if strings.HasPrefix(baseDir, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			return filepath.Join(home, baseDir[2:])
+		}
+	}
+
+	// Absolute paths
+	if filepath.IsAbs(baseDir) {
+		return filepath.Clean(baseDir)
+	}
+
+	// Relative to cwd
+	return filepath.Join(cwd, baseDir)
+}
+
+// listFiles returns files and directories within searchDir, relative to that
+// directory. Uses `git ls-files` when inside a git repo for speed and
+// .gitignore awareness, otherwise falls back to os.ReadDir.
+func listFiles(searchDir, cwd string) []FileSuggestion {
+	// Try git ls-files first (fast, respects .gitignore).
+	if files := listFilesGit(searchDir, cwd); files != nil {
+		return files
+	}
+	return listFilesReadDir(searchDir)
+}
+
+// listFilesGit uses `git ls-files` and `git ls-files --others --exclude-standard`
+// to list tracked and untracked-but-not-ignored files.
+func listFilesGit(searchDir, cwd string) []FileSuggestion {
+	// Check if we're in a git repo.
+	check := exec.Command("git", "rev-parse", "--show-toplevel")
+	check.Dir = cwd
+	if err := check.Run(); err != nil {
+		return nil
+	}
+
+	seen := make(map[string]bool)
+	var results []FileSuggestion
+
+	// Tracked files.
+	cmd := exec.Command("git", "ls-files")
+	cmd.Dir = searchDir
+	out, err := cmd.Output()
+	if err == nil {
+		for line := range strings.SplitSeq(strings.TrimSpace(string(out)), "\n") {
+			if line == "" {
+				continue
+			}
+			// Normalize separators.
+			line = filepath.ToSlash(line)
+			addFileEntries(&results, seen, line, searchDir)
+		}
+	}
+
+	// Untracked, non-ignored files.
+	cmd2 := exec.Command("git", "ls-files", "--others", "--exclude-standard")
+	cmd2.Dir = searchDir
+	out2, err := cmd2.Output()
+	if err == nil {
+		for line := range strings.SplitSeq(strings.TrimSpace(string(out2)), "\n") {
+			if line == "" {
+				continue
+			}
+			line = filepath.ToSlash(line)
+			addFileEntries(&results, seen, line, searchDir)
+		}
+	}
+
+	if len(results) == 0 {
+		return nil
+	}
+	return results
+}
+
+// addFileEntries adds the file and any intermediate directory entries to
+// results if not already seen. Paths are stored with forward slashes.
+func addFileEntries(results *[]FileSuggestion, seen map[string]bool, relPath string, searchDir string) {
+	// Add intermediate directories as suggestions (first component only).
+	parts := strings.SplitN(relPath, "/", 2)
+	if len(parts) > 1 {
+		dir := parts[0] + "/"
+		if !seen[dir] {
+			seen[dir] = true
+			*results = append(*results, FileSuggestion{RelPath: dir, IsDir: true})
+		}
+	}
+
+	// Add the file itself.
+	if !seen[relPath] {
+		seen[relPath] = true
+		*results = append(*results, FileSuggestion{RelPath: relPath, IsDir: false})
+	}
+}
+
+// listFilesReadDir is the fallback when git is not available. Lists immediate
+// children of dir via os.ReadDir, skipping hidden dirs and common noise.
+func listFilesReadDir(dir string) []FileSuggestion {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil
+	}
+
+	skip := map[string]bool{
+		".git": true, "node_modules": true, ".kit": true,
+		"__pycache__": true, ".venv": true, "vendor": true,
+	}
+
+	var results []FileSuggestion
+	for _, e := range entries {
+		name := e.Name()
+		if skip[name] {
+			continue
+		}
+		// Skip hidden files/dirs (except common config files).
+		if strings.HasPrefix(name, ".") && name != ".env" && name != ".gitignore" {
+			continue
+		}
+		if e.IsDir() {
+			results = append(results, FileSuggestion{RelPath: name + "/", IsDir: true})
+		} else {
+			results = append(results, FileSuggestion{RelPath: name, IsDir: false})
+		}
+	}
+	return results
+}
+
+// fuzzyFilterFiles scores and filters file suggestions against the query,
+// returning the top maxFileSuggestions results sorted by score descending.
+// Directories are boosted slightly so they appear near the top.
+func fuzzyFilterFiles(files []FileSuggestion, fullPrefix, query string) []FileSuggestion {
+	if query == "" && fullPrefix == "" {
+		// No filter — return all (capped).
+		if len(files) > maxFileSuggestions {
+			files = files[:maxFileSuggestions]
+		}
+		return files
+	}
+
+	// When there's a base dir but no query (e.g. "cmd/"), show everything
+	// in that directory.
+	if query == "" {
+		var filtered []FileSuggestion
+		for i := range files {
+			if strings.HasPrefix(files[i].RelPath, fullPrefix) {
+				// Only show direct children of the base directory.
+				rest := files[i].RelPath[len(fullPrefix):]
+				if rest == "" {
+					continue
+				}
+				filtered = append(filtered, files[i])
+			}
+		}
+		if len(filtered) > maxFileSuggestions {
+			filtered = filtered[:maxFileSuggestions]
+		}
+		return filtered
+	}
+
+	var scored []FileSuggestion
+	queryLower := strings.ToLower(query)
+
+	for i := range files {
+		path := files[i].RelPath
+		// When we have a fullPrefix with a dir component, only consider
+		// files under that directory.
+		if fullPrefix != query && !strings.HasPrefix(path, fullPrefix[:len(fullPrefix)-len(query)]) {
+			continue
+		}
+
+		score := scoreFilePath(queryLower, path)
+		if score <= 0 {
+			continue
+		}
+
+		// Boost directories so they appear near the top for navigation.
+		if files[i].IsDir {
+			score += 10
+		}
+
+		files[i].Score = score
+		scored = append(scored, files[i])
+	}
+
+	// Sort by score descending.
+	sort.Slice(scored, func(i, j int) bool {
+		return scored[i].Score > scored[j].Score
+	})
+
+	if len(scored) > maxFileSuggestions {
+		scored = scored[:maxFileSuggestions]
+	}
+	return scored
+}
+
+// scoreFilePath scores a file path against a fuzzy query. Higher is better.
+// Returns 0 if there is no match.
+func scoreFilePath(query, path string) int {
+	pathLower := strings.ToLower(path)
+	baseName := filepath.Base(strings.TrimSuffix(path, "/"))
+	baseNameLower := strings.ToLower(baseName)
+
+	// Exact basename match.
+	if baseNameLower == query {
+		return 1000
+	}
+
+	// Basename starts with query.
+	if strings.HasPrefix(baseNameLower, query) {
+		return 800 - len(baseName) + len(query)
+	}
+
+	// Basename contains query as substring.
+	if strings.Contains(baseNameLower, query) {
+		return 500 - len(baseName) + len(query)
+	}
+
+	// Full path contains query as substring.
+	if strings.Contains(pathLower, query) {
+		return 300 - len(path) + len(query)
+	}
+
+	// Fuzzy character match on basename.
+	if score := fuzzyCharMatch(query, baseNameLower); score > 0 {
+		return score
+	}
+
+	// Fuzzy character match on full path.
+	if score := fuzzyCharMatch(query, pathLower); score > 0 {
+		return score - 50
+	}
+
+	return 0
+}
+
+// fuzzyCharMatch performs character-by-character fuzzy matching. Returns a
+// positive score if all query characters appear in order in the target.
+func fuzzyCharMatch(query, target string) int {
+	if utf8.RuneCountInString(query) > utf8.RuneCountInString(target) {
+		return 0
+	}
+
+	qRunes := []rune(query)
+	tRunes := []rune(target)
+	qi := 0
+	score := 100
+	consecutive := 0
+
+	for ti := 0; ti < len(tRunes) && qi < len(qRunes); ti++ {
+		if tRunes[ti] == qRunes[qi] {
+			qi++
+			consecutive++
+			score += consecutive * 5
+		} else {
+			consecutive = 0
+			score -= 2
+		}
+	}
+
+	if qi < len(qRunes) {
+		return 0
+	}
+	return score
+}

internal/ui/input.go

@@ -1,12 +1,15 @@
 package ui
 
 import (
+	"fmt"
 	"strings"
 
 	"charm.land/bubbles/v2/key"
 	"charm.land/bubbles/v2/textarea"
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/clipboard"
 )
 
 // InputComponent is the interactive text input field for the parent AppModel.
@@ -43,12 +46,34 @@ type InputComponent struct {
 	argCommand   string         // command prefix for arg mode (e.g. "/bookmark")
 	argSynthCmds []SlashCommand // backing storage for synthetic arg entries
 
+	// File completion state. When the user types @ followed by a partial
+	// file path, the popup shows file/directory suggestions from the cwd.
+	fileMode        bool             // true when showing @file completions
+	filePrefix      string           // current text after @ being matched
+	fileAtStartIdx  int              // byte offset of @ in the textarea value
+	fileSuggestions []FileSuggestion // backing storage for file entries
+	fileSynthCmds   []SlashCommand   // synthetic SlashCommands wrapping file entries
+
+	// cwd is the working directory used for @file path resolution and
+	// autocomplete suggestions. Set by the parent via SetCwd.
+	cwd string
+
 	// appCtrl is used for slash commands that mutate app state.
 	// May be nil in tests; nil-safe.
 	appCtrl AppController
 
 	// hideHint suppresses the "enter submit · ctrl+j..." hint text.
 	hideHint bool
+
+	// pendingImages holds clipboard images attached to the next submission.
+	// Images are added via Ctrl+V and cleared on submit or Ctrl+U.
+	pendingImages []ImageAttachment
+}
+
+// clipboardImageMsg is the result of an async clipboard image read.
+type clipboardImageMsg struct {
+	image *ImageAttachment
+	err   error
 }
 
 // NewInputComponent creates a new InputComponent with the given width, title,
@@ -90,6 +115,12 @@ func NewInputComponent(width int, title string, appCtrl AppController) *InputCom
 	}
 }
 
+// SetCwd sets the working directory used for @file autocomplete suggestions
+// and path resolution. Should be called by the parent after construction.
+func (s *InputComponent) SetCwd(cwd string) {
+	s.cwd = cwd
+}
+
 // Init implements tea.Model. Starts the cursor blink animation.
 func (s *InputComponent) Init() tea.Cmd {
 	return textarea.Blink
@@ -119,6 +150,16 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		s.textarea.SetWidth(msg.Width - 8)
 		return s, nil
 
+	case clipboardImageMsg:
+		if msg.err != nil {
+			// Silently ignore — no image on clipboard or tool unavailable.
+			return s, nil
+		}
+		if msg.image != nil {
+			s.pendingImages = append(s.pendingImages, *msg.image)
+		}
+		return s, nil
+
 	case tea.KeyPressMsg:
 		if !s.showPopup {
 			switch msg.String() {
@@ -128,6 +169,15 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				s.textarea.CursorEnd()
 				s.lastValue = ""
 				return s, s.handleSubmit(value)
+			case "ctrl+v":
+				// Try to read an image from the clipboard asynchronously.
+				return s, readClipboardImageCmd()
+			case "ctrl+u":
+				// Clear all pending image attachments.
+				if len(s.pendingImages) > 0 {
+					s.pendingImages = nil
+					return s, nil
+				}
 			}
 		}
 
@@ -148,19 +198,29 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 			case key.Matches(msg, key.NewBinding(key.WithKeys("tab"))):
 				if s.selected < len(s.filtered) {
-					if s.argMode {
+					if s.fileMode {
+						s.applyFileCompletion(s.selected)
+					} else if s.argMode {
 						s.textarea.SetValue(s.argCommand + " " + s.filtered[s.selected].Command.Name)
+						s.showPopup = false
+						s.selected = 0
 					} else {
 						s.textarea.SetValue(s.filtered[s.selected].Command.Name)
+						s.showPopup = false
+						s.selected = 0
 					}
-					s.showPopup = false
-					s.selected = 0
 					s.textarea.CursorEnd()
 				}
 				return s, nil
 
 			case key.Matches(msg, key.NewBinding(key.WithKeys("enter"))):
 				if s.selected < len(s.filtered) {
+					if s.fileMode {
+						// Apply file completion but don't submit.
+						s.applyFileCompletion(s.selected)
+						s.textarea.CursorEnd()
+						return s, nil
+					}
 					// Populate textarea with selected item and submit on next tick.
 					if s.argMode {
 						s.textarea.SetValue(s.argCommand + " " + s.filtered[s.selected].Command.Name)
@@ -190,7 +250,37 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if value != s.lastValue {
 			s.lastValue = value
 			lines := strings.Split(value, "\n")
-			if len(lines) == 1 && strings.HasPrefix(lines[0], "/") {
+			line := lines[len(lines)-1] // current line (last line for multi-line)
+
+			// Check for @file trigger first.
+			cursorCol := len(line) // approximate: cursor is at end after typing
+			if hasAt, prefix, atIdx := ExtractAtPrefix(line, cursorCol); hasAt && s.cwd != "" {
+				suggestions := GetFileSuggestions(prefix, s.cwd)
+				if len(suggestions) > 0 {
+					s.showPopup = true
+					s.fileMode = true
+					s.argMode = false
+					s.filePrefix = prefix
+					s.fileAtStartIdx = atIdx
+					s.fileSuggestions = suggestions
+					s.fileSynthCmds = make([]SlashCommand, len(suggestions))
+					s.filtered = make([]FuzzyMatch, len(suggestions))
+					for i, fs := range suggestions {
+						name := fs.RelPath
+						desc := ""
+						if fs.IsDir {
+							desc = "directory"
+						}
+						s.fileSynthCmds[i] = SlashCommand{Name: name, Description: desc}
+						s.filtered[i] = FuzzyMatch{Command: &s.fileSynthCmds[i], Score: fs.Score}
+					}
+					s.selected = 0
+				} else {
+					s.showPopup = false
+					s.fileMode = false
+				}
+			} else if len(lines) == 1 && strings.HasPrefix(lines[0], "/") {
+				s.fileMode = false
 				if !strings.Contains(lines[0], " ") {
 					// Command name completion.
 					s.showPopup = true
@@ -210,6 +300,7 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			} else {
 				s.showPopup = false
 				s.argMode = false
+				s.fileMode = false
 			}
 		}
 		return s, cmd
@@ -223,12 +314,34 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 // handleSubmit processes the submitted text. Slash commands that affect app
 // state are executed here; /quit returns tea.Quit; everything else returns a
 // submitMsg tea.Cmd for the parent to forward to app.Run().
+//
+// Shell command prefixes (matching pi's behavior):
+//   - !cmd  → execute shell command, output INCLUDED in LLM context
+//   - !!cmd → execute shell command, output EXCLUDED from LLM context
 func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 	trimmed := strings.TrimSpace(value)
 	if trimmed == "" {
 		return nil
 	}
 
+	// Check for shell command prefixes before slash commands. Test !! first
+	// (more specific) to avoid matching the single-! case for double-bang.
+	if strings.HasPrefix(trimmed, "!!") {
+		cmd := strings.TrimSpace(trimmed[2:])
+		if cmd != "" {
+			return func() tea.Msg {
+				return shellCommandMsg{Command: cmd, ExcludeFromContext: true}
+			}
+		}
+	} else if strings.HasPrefix(trimmed, "!") {
+		cmd := strings.TrimSpace(trimmed[1:])
+		if cmd != "" {
+			return func() tea.Msg {
+				return shellCommandMsg{Command: cmd, ExcludeFromContext: false}
+			}
+		}
+	}
+
 	// Resolve via canonical command lookup so aliases are handled uniformly.
 	// Only /quit and /clear are handled locally — /clear-queue must go
 	// through the parent model so it can update queueCount directly
@@ -249,9 +362,12 @@ func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 	}
 
 	// For all other input (including unrecognised slash commands and regular
-	// prompts) hand off to the parent via submitMsg.
+	// prompts) hand off to the parent via submitMsg. Attach any pending
+	// images and clear them.
+	images := s.pendingImages
+	s.pendingImages = nil
 	return func() tea.Msg {
-		return submitMsg{Text: trimmed}
+		return submitMsg{Text: trimmed, Images: images}
 	}
 }
 
@@ -286,14 +402,26 @@ func (s *InputComponent) View() tea.View {
 		view.WriteString(s.renderPopup())
 	}
 
+	// Show image attachment indicator when images are pending.
+	if len(s.pendingImages) > 0 {
+		imgStyle := lipgloss.NewStyle().
+			Foreground(lipgloss.Color("39")).
+			PaddingLeft(3)
+
+		label := fmt.Sprintf("[%d image(s) attached] ctrl+u to clear", len(s.pendingImages))
+		view.WriteString("\n")
+		view.WriteString(imgStyle.Render(label))
+	}
+
 	if !s.hideHint {
 		helpStyle := lipgloss.NewStyle().
 			Foreground(lipgloss.Color("240")).
 			MarginTop(1).
 			PaddingLeft(3)
 
+		hint := "enter submit • ctrl+j / alt+enter new line • ctrl+v paste image"
 		view.WriteString("\n")
-		view.WriteString(helpStyle.Render("enter submit • ctrl+j / alt+enter new line"))
+		view.WriteString(helpStyle.Render(hint))
 	}
 
 	return tea.NewView(containerStyle.Render(view.String()))
@@ -335,16 +463,32 @@ func (s *InputComponent) renderPopup() string {
 			descStyle = descStyle.Foreground(lipgloss.Color("250"))
 		}
 
-		nameWidth := 15
-		name := nameStyle.Width(nameWidth - 2).Render(sc.Name)
+		if s.fileMode {
+			// File mode: use full width for the path, show description
+			// (e.g. "directory") inline after a gap.
+			maxNameLen := s.width - 24
+			displayName := sc.Name
+			if len(displayName) > maxNameLen && maxNameLen > 3 {
+				displayName = displayName[:maxNameLen-3] + "..."
+			}
+			name := nameStyle.Render(displayName)
+			if sc.Description != "" {
+				items = append(items, indicator+name+"  "+descStyle.Render(sc.Description))
+			} else {
+				items = append(items, indicator+name)
+			}
+		} else {
+			nameWidth := 15
+			name := nameStyle.Width(nameWidth - 2).Render(sc.Name)
 
-		desc := sc.Description
-		maxDescLen := s.width - nameWidth - 14
-		if len(desc) > maxDescLen && maxDescLen > 3 {
-			desc = desc[:maxDescLen-3] + "..."
+			desc := sc.Description
+			maxDescLen := s.width - nameWidth - 14
+			if len(desc) > maxDescLen && maxDescLen > 3 {
+				desc = desc[:maxDescLen-3] + "..."
+			}
+
+			items = append(items, indicator+name+descStyle.Render(desc))
 		}
-
-		items = append(items, indicator+name+descStyle.Render(desc))
 	}
 
 	if startIdx > 0 {
@@ -404,3 +548,86 @@ func (s *InputComponent) findCommandWithComplete(name string) *SlashCommand {
 	}
 	return nil
 }
+
+// readClipboardImageCmd returns a tea.Cmd that reads an image from the system
+// clipboard. The result is delivered as a clipboardImageMsg.
+func readClipboardImageCmd() tea.Cmd {
+	return func() tea.Msg {
+		img, err := clipboard.ReadImage()
+		if err != nil {
+			return clipboardImageMsg{err: err}
+		}
+		return clipboardImageMsg{
+			image: &ImageAttachment{
+				Data:      img.Data,
+				MediaType: img.MediaType,
+			},
+		}
+	}
+}
+
+// ClearPendingImages removes all pending image attachments and returns them.
+// Used by the parent model when consuming images for submission.
+func (s *InputComponent) ClearPendingImages() []ImageAttachment {
+	images := s.pendingImages
+	s.pendingImages = nil
+	return images
+}
+
+// PendingImageCount returns the number of images currently attached.
+func (s *InputComponent) PendingImageCount() int {
+	return len(s.pendingImages)
+}
+
+// applyFileCompletion replaces the @prefix in the textarea with the selected
+// file suggestion. For directories, it keeps the popup open for further
+// drilling. For files, it closes the popup and adds a trailing space.
+func (s *InputComponent) applyFileCompletion(idx int) {
+	if idx >= len(s.fileSuggestions) {
+		return
+	}
+
+	suggestion := s.fileSuggestions[idx]
+	value := s.textarea.Value()
+
+	// Build the replacement text. The @ and everything after it up to the
+	// cursor should be replaced with @<selected path>.
+	// Find the current line's contribution.
+	lines := strings.Split(value, "\n")
+	lastLine := lines[len(lines)-1]
+
+	// Reconstruct: everything before the @ on the last line + @<path>
+	beforeAt := lastLine[:s.fileAtStartIdx]
+	needsQuote := strings.Contains(suggestion.RelPath, " ")
+
+	var replacement string
+	if needsQuote {
+		replacement = `@"` + suggestion.RelPath + `"`
+	} else {
+		replacement = "@" + suggestion.RelPath
+	}
+
+	// For files, add a trailing space. For directories, don't — allow
+	// continued drilling into the directory.
+	if !suggestion.IsDir {
+		replacement += " "
+	}
+
+	newLastLine := beforeAt + replacement
+
+	// Reconstruct the full value with the updated last line.
+	lines[len(lines)-1] = newLastLine
+	newValue := strings.Join(lines, "\n")
+
+	s.textarea.SetValue(newValue)
+	s.textarea.CursorEnd()
+
+	if suggestion.IsDir {
+		// Keep popup open — trigger a refresh for the new directory.
+		s.lastValue = "" // force re-evaluation on next update tick
+	} else {
+		s.showPopup = false
+		s.fileMode = false
+		s.selected = 0
+	}
+}

internal/ui/model.go

@@ -1,14 +1,21 @@
 package ui
 
 import (
+	"bytes"
+	"context"
 	"fmt"
 	"os"
+	"os/exec"
 	"strings"
 	"time"
 
 	tea "charm.land/bubbletea/v2"
+	"charm.land/fantasy"
 	"charm.land/lipgloss/v2"
+
 	"github.com/mark3labs/kit/internal/app"
+	"github.com/mark3labs/kit/internal/core"
+	"github.com/mark3labs/kit/internal/models"
 	"github.com/mark3labs/kit/internal/session"
 )
 
@@ -34,6 +41,9 @@ const (
 	// stateOverlay means an extension-triggered modal overlay dialog is active.
 	// The overlay takes over the full view until the user completes or cancels.
 	stateOverlay
+
+	// stateModelSelector means the /model selector overlay is active.
+	stateModelSelector
 )
 
 // AppController is the interface the parent TUI model uses to interact with the
@@ -72,6 +82,16 @@ type AppController interface {
 	// results back to the TUI without going through tea.Cmd (which can stall
 	// when the goroutine blocks on interactive prompts).
 	SendEvent(tea.Msg)
+	// AddContextMessage adds a user-role message to the conversation history
+	// without triggering an LLM response. Used by the ! shell command prefix
+	// to inject command output into context so the LLM can reference it in
+	// subsequent turns.
+	AddContextMessage(text string)
+	// RunWithFiles queues a multimodal prompt (text + images) for execution.
+	// Behaves like Run but includes file parts (e.g. clipboard images)
+	// alongside the text. Returns the current queue depth (0 = started
+	// immediately, >0 = queued).
+	RunWithFiles(prompt string, files []fantasy.FilePart) int
 }
 
 // SkillItem holds display metadata about a loaded skill for the startup
@@ -201,6 +221,10 @@ type AppModelOptions struct {
 	// (e.g. GPU fallback info). Displayed at startup when non-empty.
 	LoadingMessage string
 
+	// Cwd is the working directory for @file autocomplete and path resolution.
+	// If empty, @file features are disabled.
+	Cwd string
+
 	// Width is the initial terminal width in columns.
 	Width int
 
@@ -294,6 +318,24 @@ type AppModelOptions struct {
 	// commands. Called on WidgetUpdateEvent to refresh the command list
 	// after an extension hot-reload. May be nil if no extensions loaded.
 	GetExtensionCommands func() []ExtensionCommand
+
+	// SetModel changes the active model at runtime. The model string uses
+	// "provider/model" format (e.g. "anthropic/claude-sonnet-4-5-20250929").
+	// Returns an error if the model string is invalid or the provider cannot
+	// be created. May be nil if model switching is not supported.
+	SetModel func(modelString string) error
+
+	// EmitModelChange fires the OnModelChange extension event after a
+	// successful model switch. Parameters are (newModel, previousModel, source).
+	// May be nil if extensions are not loaded.
+	EmitModelChange func(newModel, previousModel, source string)
+
+	// ThinkingLevel is the initial thinking level (e.g. "off", "medium").
+	ThinkingLevel string
+	// IsReasoningModel is true when the current model supports reasoning.
+	IsReasoningModel bool
+	// SetThinkingLevel changes the thinking level on the agent/provider.
+	SetThinkingLevel func(level string) error
 }
 
 // AppModel is the root Bubble Tea model for the interactive TUI. It owns the
@@ -415,6 +457,16 @@ type AppModel struct {
 	// Returns (cancelled, reason). May be nil if no extensions are loaded.
 	emitBeforeSessionSwitch func(reason string) (bool, string)
 
+	// thinkingLevel is the current extended thinking level.
+	thinkingLevel string
+	// thinkingVisible controls whether reasoning blocks are shown or collapsed.
+	thinkingVisible bool
+	// isReasoningModel is true when the current model supports reasoning.
+	isReasoningModel bool
+	// setThinkingLevel is a callback to change the thinking level on the agent.
+	// It takes the new level string and returns an error if the change fails.
+	setThinkingLevel func(level string) error
+
 	// getGlobalShortcuts returns extension-registered keyboard shortcuts.
 	// May be nil if no extensions are loaded.
 	getGlobalShortcuts func() map[string]func()
@@ -423,6 +475,16 @@ type AppModel struct {
 	// to refresh the command list after an extension hot-reload. May be nil.
 	getExtensionCommands func() []ExtensionCommand
 
+	// setModel changes the active model at runtime. Wired from cmd/root.go.
+	// May be nil if model switching is not supported.
+	setModel func(modelString string) error
+
+	// emitModelChange fires the OnModelChange extension event. May be nil.
+	emitModelChange func(newModel, previousModel, source string)
+
+	// modelSelector is the model selection overlay, active in stateModelSelector.
+	modelSelector *ModelSelectorComponent
+
 	// prompt holds the state of an active interactive prompt overlay. Nil
 	// when no prompt is active. Managed by updatePromptState().
 	prompt *promptOverlay
@@ -449,6 +511,9 @@ type AppModel struct {
 	// so the model can return to it when the overlay completes.
 	preOverlayState appState
 
+	// cwd is the working directory for @file path resolution.
+	cwd string
+
 	// width and height track the terminal dimensions.
 	width  int
 	height int
@@ -479,6 +544,10 @@ type streamComponentIface interface {
 	// Returns "" when the spinner is not active. The parent renders this in the
 	// status bar so the spinner never changes the view height.
 	SpinnerView() string
+	// SetThinkingVisible sets whether reasoning blocks are shown or collapsed.
+	SetThinkingVisible(visible bool)
+	// HasReasoning returns true if any reasoning content has been accumulated.
+	HasReasoning() bool
 }
 
 // --------------------------------------------------------------------------
@@ -526,6 +595,7 @@ func NewAppModel(appCtrl AppController, opts AppModelOptions) *AppModel {
 		serverNames:    opts.ServerNames,
 		toolNames:      opts.ToolNames,
 		usageTracker:   opts.UsageTracker,
+		cwd:            opts.Cwd,
 		width:          width,
 		height:         height,
 	}
@@ -542,6 +612,12 @@ func NewAppModel(appCtrl AppController, opts AppModelOptions) *AppModel {
 	m.emitBeforeSessionSwitch = opts.EmitBeforeSessionSwitch
 	m.getGlobalShortcuts = opts.GetGlobalShortcuts
 	m.getExtensionCommands = opts.GetExtensionCommands
+	m.setModel = opts.SetModel
+	m.emitModelChange = opts.EmitModelChange
+	m.thinkingLevel = opts.ThinkingLevel
+	m.thinkingVisible = true // default to showing thinking blocks
+	m.isReasoningModel = opts.IsReasoningModel
+	m.setThinkingLevel = opts.SetThinkingLevel
 
 	// Store context/skills metadata and tool counts for startup display.
 	m.contextPaths = opts.ContextPaths
@@ -552,6 +628,11 @@ func NewAppModel(appCtrl AppController, opts AppModelOptions) *AppModel {
 	// Wire up child components now that we have the concrete implementations.
 	m.input = NewInputComponent(width, "Enter your prompt (Type /help for commands, Ctrl+C to quit)", appCtrl)
 
+	// Wire up cwd for @file autocomplete.
+	if ic, ok := m.input.(*InputComponent); ok && opts.Cwd != "" {
+		ic.SetCwd(opts.Cwd)
+	}
+
 	// Merge extension commands into the InputComponent's autocomplete source.
 	if ic, ok := m.input.(*InputComponent); ok && len(opts.ExtensionCommands) > 0 {
 		for _, ec := range opts.ExtensionCommands {
@@ -565,6 +646,7 @@ func NewAppModel(appCtrl AppController, opts AppModelOptions) *AppModel {
 	}
 
 	m.stream = NewStreamComponent(opts.CompactMode, width, opts.ModelName)
+	m.stream.SetThinkingVisible(m.thinkingVisible)
 
 	// Propagate initial height distribution to children.
 	m.distributeHeight()
@@ -705,34 +787,31 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				}
 			}
 
-			// Emit before-fork event — extensions can cancel the operation.
+			// Emit before-fork event in a goroutine so that extension handlers
+			// can call blocking operations (e.g. ctx.PromptConfirm) without
+			// deadlocking the BubbleTea event loop.
 			if m.emitBeforeFork != nil {
-				if cancelled, reason := m.emitBeforeFork(targetID, msg.IsUser, msg.UserText); cancelled {
-					m.treeSelector = nil
-					m.state = stateInput
-					return m, m.printSystemMessage(reason)
-				}
+				emit := m.emitBeforeFork
+				ctrl := m.appCtrl
+				forkTargetID := targetID
+				forkIsUser := msg.IsUser
+				forkUserText := msg.UserText
+				go func() {
+					cancelled, reason := emit(forkTargetID, forkIsUser, forkUserText)
+					ctrl.SendEvent(beforeForkResultMsg{
+						cancelled: cancelled,
+						reason:    reason,
+						targetID:  forkTargetID,
+						isUser:    forkIsUser,
+						userText:  forkUserText,
+					})
+				}()
+				m.treeSelector = nil
+				m.state = stateInput
+				return m, func() tea.Msg { return nil }
 			}
 
-			_ = ts.Branch(targetID)
-			m.appCtrl.ClearMessages()
-
-			// If it was a user message, populate the input with the text.
-			if msg.IsUser && msg.UserText != "" {
-				if ic, ok := m.input.(*InputComponent); ok {
-					ic.textarea.SetValue(msg.UserText)
-					ic.textarea.CursorEnd()
-				}
-			}
-
-			cmds = append(cmds, m.printSystemMessage(
-				fmt.Sprintf("Navigated to branch point. %s",
-					func() string {
-						if msg.IsUser {
-							return "Edit and resubmit to create a new branch."
-						}
-						return "Continue from this point."
-					}())))
+			cmds = append(cmds, m.performFork(targetID, msg.IsUser, msg.UserText))
 		}
 		m.treeSelector = nil
 		m.state = stateInput
@@ -743,6 +822,39 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		m.state = stateInput
 		return m, nil
 
+	// ── Model selector events ────────────────────────────────────────────────
+	case ModelSelectedMsg:
+		m.modelSelector = nil
+		m.state = stateInput
+		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)))
+			} else {
+				// Update display state directly — we cannot use
+				// NotifyModelChanged (prog.Send) from inside Update()
+				// without deadlocking BubbleTea.
+				parts := strings.SplitN(msg.ModelString, "/", 2)
+				if len(parts) == 2 {
+					m.providerName = parts[0]
+					m.modelName = parts[1]
+				}
+				cmds = append(cmds, m.printSystemMessage(fmt.Sprintf("Switched to %s", msg.ModelString)))
+				if m.emitModelChange != nil {
+					emit := m.emitModelChange
+					newModel := msg.ModelString
+					prev := previousModel
+					go emit(newModel, prev, "user")
+				}
+			}
+		}
+		return m, tea.Batch(cmds...)
+
+	case ModelSelectorCancelledMsg:
+		m.modelSelector = nil
+		m.state = stateInput
+		return m, nil
+
 	// ── Window resize ────────────────────────────────────────────────────────
 	case tea.WindowSizeMsg:
 		m.width = msg.Width
@@ -793,6 +905,23 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			}
 		}
 
+		// Thinking keybindings — only when the model supports reasoning.
+		if m.isReasoningModel {
+			switch msg.String() {
+			case "ctrl+t":
+				// Toggle thinking block visibility.
+				m.thinkingVisible = !m.thinkingVisible
+				if m.stream != nil {
+					m.stream.SetThinkingVisible(m.thinkingVisible)
+				}
+				return m, tea.Batch(cmds...)
+			case "shift+tab":
+				// Cycle thinking level.
+				m.cycleThinkingLevel()
+				return m, tea.Batch(cmds...)
+			}
+		}
+
 		// Route to tree selector when active.
 		if m.state == stateTreeSelector && m.treeSelector != nil {
 			updated, cmd := m.treeSelector.Update(msg)
@@ -801,6 +930,14 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			return m, tea.Batch(cmds...)
 		}
 
+		// Route to model selector when active.
+		if m.state == stateModelSelector && m.modelSelector != nil {
+			updated, cmd := m.modelSelector.Update(msg)
+			m.modelSelector = updated.(*ModelSelectorComponent)
+			cmds = append(cmds, cmd)
+			return m, tea.Batch(cmds...)
+		}
+
 		switch msg.String() {
 		case "esc":
 			if m.state == stateWorking {
@@ -844,16 +981,18 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 						// If remap target is unrecognized, fall through to normal handling.
 					case EditorKeySubmit:
 						text := action.SubmitText
+						var images []ImageAttachment
 						if text == "" {
 							if ic, ok := m.input.(*InputComponent); ok {
 								text = strings.TrimSpace(ic.textarea.Value())
+								images = ic.ClearPendingImages()
 								ic.textarea.SetValue("")
 								ic.textarea.CursorEnd()
 							}
 						}
 						if text != "" {
 							cmds = append(cmds, func() tea.Msg {
-								return submitMsg{Text: text}
+								return submitMsg{Text: text, Images: images}
 							})
 						}
 						intercepted = true
@@ -882,14 +1021,28 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			return m, tea.Batch(cmds...)
 		}
 
-		// /compact supports optional args: "/compact Focus on API decisions".
+		// /compact and /model support optional args (e.g. "/compact Focus on API",
+		// "/model anthropic/claude-haiku-3-5-20241022").
 		// GetCommandByName won't match the full text, so check the prefix.
 		if name, args, ok := strings.Cut(msg.Text, " "); ok {
-			if sc := GetCommandByName(name); sc != nil && sc.Name == "/compact" {
-				if cmd := m.handleCompactCommand(strings.TrimSpace(args)); cmd != nil {
-					cmds = append(cmds, cmd)
+			if sc := GetCommandByName(name); sc != nil {
+				switch sc.Name {
+				case "/compact":
+					if cmd := m.handleCompactCommand(strings.TrimSpace(args)); cmd != nil {
+						cmds = append(cmds, cmd)
+					}
+					return m, tea.Batch(cmds...)
+				case "/model":
+					if cmd := m.handleModelCommand(strings.TrimSpace(args)); cmd != nil {
+						cmds = append(cmds, cmd)
+					}
+					return m, tea.Batch(cmds...)
+				case "/thinking":
+					if cmd := m.handleThinkingCommand(strings.TrimSpace(args)); cmd != nil {
+						cmds = append(cmds, cmd)
+					}
+					return m, tea.Batch(cmds...)
 				}
-				return m, tea.Batch(cmds...)
 			}
 		}
 
@@ -901,28 +1054,65 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 
 		// Regular prompt — forward to the app layer.
+		// Preprocess @file references: expand them into XML-wrapped file
+		// content before sending to the agent. The display text (shown in
+		// scrollback) uses the original user text so the UI stays clean.
+		processedText := msg.Text
+		if m.cwd != "" {
+			processedText = ProcessFileAttachments(msg.Text, m.cwd)
+		}
+
+		// Convert image attachments to fantasy.FilePart for the app layer.
+		var fileParts []fantasy.FilePart
+		for _, img := range msg.Images {
+			fileParts = append(fileParts, fantasy.FilePart{
+				Data:      img.Data,
+				MediaType: img.MediaType,
+			})
+		}
+
+		// Build display text for scrollback (include image count if any).
+		displayText := msg.Text
+		if len(msg.Images) > 0 {
+			displayText = fmt.Sprintf("%s\n[%d image(s) attached]", msg.Text, len(msg.Images))
+		}
+
 		if m.appCtrl != nil {
 			// Run returns the queue depth: >0 means the prompt was queued
 			// (agent is busy). We update queuedMessages directly here
 			// instead of relying on an event from prog.Send(), which would
 			// deadlock when called synchronously from within Update().
-			if qLen := m.appCtrl.Run(msg.Text); qLen > 0 {
+			var qLen int
+			if len(fileParts) > 0 {
+				qLen = m.appCtrl.RunWithFiles(processedText, fileParts)
+			} else {
+				qLen = m.appCtrl.Run(processedText)
+			}
+			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).
-				m.queuedMessages = append(m.queuedMessages, msg.Text)
+				m.queuedMessages = append(m.queuedMessages, displayText)
 				m.distributeHeight()
 			} else {
 				// Started immediately: print to scrollback now.
-				cmds = append(cmds, m.printUserMessage(msg.Text))
+				cmds = append(cmds, m.printUserMessage(displayText))
 			}
 		} else {
-			cmds = append(cmds, m.printUserMessage(msg.Text))
+			cmds = append(cmds, m.printUserMessage(displayText))
 		}
 		if m.state != stateWorking {
 			m.state = stateWorking
 		}
 
+	// ── Shell command (! / !!) ───────────────────────────────────────────────
+	case shellCommandMsg:
+		// Execute the shell command asynchronously so the TUI stays responsive.
+		cmds = append(cmds, m.executeShellCommand(msg))
+
+	case shellCommandResultMsg:
+		cmds = append(cmds, m.handleShellCommandResult(msg))
+
 	// ── App layer events ─────────────────────────────────────────────────────
 
 	case app.SpinnerEvent:
@@ -941,6 +1131,12 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			cmds = append(cmds, cmd)
 		}
 
+	case app.ReasoningChunkEvent:
+		if m.stream != nil {
+			_, cmd := m.stream.Update(msg)
+			cmds = append(cmds, cmd)
+		}
+
 	case app.StreamChunkEvent:
 		if m.stream != nil {
 			_, cmd := m.stream.Update(msg)
@@ -976,13 +1172,17 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		// double-printing.
 
 	case app.ResponseCompleteEvent:
-		// Non-streaming mode: this carries the full response text (StreamChunkEvents
-		// never fire). Print it immediately.
-		if msg.Content != "" {
+		// This event fires for both streaming and non-streaming paths.
+		// In streaming mode, the content was already delivered via StreamChunkEvents
+		// and is sitting in the stream component (possibly with reasoning). Don't
+		// print or reset — flushStreamContent() handles it on the next step.
+		// 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))
-		}
-		if m.stream != nil {
-			m.stream.Reset() // stop spinner
+			if m.stream != nil {
+				m.stream.Reset()
+			}
 		}
 
 	case app.MessageCreatedEvent:
@@ -1163,6 +1363,24 @@ func (m *AppModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			cmds = append(cmds, 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))
+		} else {
+			cmds = append(cmds, m.performNewSession())
+		}
+
+	case beforeForkResultMsg:
+		// 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))
+		} else {
+			cmds = append(cmds, m.performFork(msg.targetID, msg.isUser, msg.userText))
+		}
+
 	case app.ExtensionPrintEvent:
 		// Extension output — route through styled renderers when a level is set.
 		switch msg.Level {
@@ -1203,6 +1421,11 @@ func (m *AppModel) View() tea.View {
 		return m.treeSelector.View()
 	}
 
+	// Model selector overlay replaces the normal layout.
+	if m.state == stateModelSelector && m.modelSelector != nil {
+		return m.modelSelector.View()
+	}
+
 	// Overlay dialog replaces the normal layout.
 	if m.state == stateOverlay && m.overlay != nil {
 		return tea.NewView(m.overlay.Render())
@@ -1314,8 +1537,14 @@ func (m *AppModel) renderStatusBar() string {
 		leftSide = m.stream.SpinnerView()
 	}
 
-	// Middle: extension status bar entries (sorted by priority).
+	// Middle: thinking level (when reasoning model) + extension status bar entries.
 	var middleParts []string
+	if m.isReasoningModel && m.thinkingLevel != "" && m.thinkingLevel != "off" {
+		thinkingLabel := "Thinking: " + m.thinkingLevel
+		middleParts = append(middleParts, lipgloss.NewStyle().
+			Foreground(theme.Secondary).
+			Render(thinkingLabel))
+	}
 	if m.getStatusBarEntries != nil {
 		entries := m.getStatusBarEntries()
 		for _, e := range entries {
@@ -1359,6 +1588,35 @@ func (m *AppModel) renderStatusBar() string {
 	return leftSide + middleSide + strings.Repeat(" ", gap) + rightSide
 }
 
+// cycleThinkingLevel advances to the next thinking level and applies it.
+func (m *AppModel) cycleThinkingLevel() {
+	levels := []string{"off", "minimal", "low", "medium", "high"}
+	current := m.thinkingLevel
+	if current == "" {
+		current = "off"
+	}
+
+	// Find current index and advance to next.
+	idx := 0
+	for i, l := range levels {
+		if l == current {
+			idx = i
+			break
+		}
+	}
+	next := levels[(idx+1)%len(levels)]
+	m.thinkingLevel = next
+
+	// Apply the change to the agent/provider.
+	if m.setThinkingLevel != nil {
+		// Run in goroutine to avoid blocking the event loop (provider
+		// recreation may take time).
+		go func() {
+			_ = m.setThinkingLevel(next)
+		}()
+	}
+}
+
 // renderSeparator renders the separator line with an optional queue count badge.
 func (m *AppModel) renderSeparator() string {
 	theme := GetTheme()
@@ -1542,6 +1800,10 @@ func (m *AppModel) handleSlashCommand(sc *SlashCommand) tea.Cmd {
 		return m.printUsageMessage()
 	case "/reset-usage":
 		return m.printResetUsage()
+	case "/model":
+		return m.handleModelCommand("")
+	case "/thinking":
+		return m.handleThinkingCommand("")
 	case "/compact":
 		return m.handleCompactCommand("")
 	case "/clear":
@@ -1697,7 +1959,10 @@ func (m *AppModel) printHelpMessage() tea.Cmd {
 		help += skillHelp.String()
 	}
 
-	help += "**Keys:**\n" +
+	help += "**Shell Commands:**\n" +
+		"- `!command`: Run shell command, output included in LLM context\n" +
+		"- `!!command`: Run shell command, output excluded from LLM context\n\n" +
+		"**Keys:**\n" +
 		"- `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."
@@ -1967,6 +2232,93 @@ func remapKey(name string) (tea.KeyPressMsg, bool) {
 	}
 }
 
+// --------------------------------------------------------------------------
+// Model command handler
+// --------------------------------------------------------------------------
+
+// handleModelCommand handles the /model slash command. With no arguments, it
+// opens an interactive model selector overlay with fuzzy finding. With an
+// argument (e.g. "/model anthropic/claude-haiku-3-5-20241022"), it switches
+// to that model directly.
+func (m *AppModel) handleModelCommand(args string) tea.Cmd {
+	if m.setModel == nil {
+		return m.printSystemMessage("Model switching is not available.")
+	}
+
+	if args == "" {
+		// Open the interactive model selector.
+		currentModel := m.providerName + "/" + m.modelName
+		m.modelSelector = NewModelSelector(currentModel, m.width, m.height)
+		m.state = stateModelSelector
+		return nil
+	}
+
+	// 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))
+	}
+
+	// Update display state directly (cannot use prog.Send from Update).
+	parts := strings.SplitN(args, "/", 2)
+	if len(parts) == 2 {
+		m.providerName = parts[0]
+		m.modelName = parts[1]
+	}
+
+	if m.emitModelChange != nil {
+		emit := m.emitModelChange
+		prev := previousModel
+		newModel := args
+		go emit(newModel, prev, "user")
+	}
+
+	return m.printSystemMessage(fmt.Sprintf("Switched to %s", args))
+}
+
+// --------------------------------------------------------------------------
+// Thinking command handler
+// --------------------------------------------------------------------------
+
+// handleThinkingCommand changes or displays the current thinking/reasoning level.
+// With no arguments, it shows the current level. With a level argument (off,
+// 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.")
+	}
+
+	if args == "" {
+		// Show current level with descriptions.
+		var lines []string
+		levels := models.ThinkingLevels()
+		for _, l := range levels {
+			marker := "  "
+			if string(l) == m.thinkingLevel {
+				marker = "▸ "
+			}
+			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"))
+	}
+
+	// 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))
+	}
+
+	// Apply the change.
+	m.thinkingLevel = string(level)
+	if m.setThinkingLevel != nil {
+		go func() {
+			_ = m.setThinkingLevel(string(level))
+		}()
+	}
+	return m.printSystemMessage(fmt.Sprintf("Thinking level set to: %s — %s", level, models.ThinkingLevelDescription(level)))
+}
+
 // --------------------------------------------------------------------------
 // Tree session command handlers
 // --------------------------------------------------------------------------
@@ -2004,13 +2356,28 @@ func (m *AppModel) handleForkCommand() tea.Cmd {
 
 // handleNewCommand starts a fresh session by resetting the tree leaf.
 func (m *AppModel) handleNewCommand() tea.Cmd {
-	// Emit before-session-switch event — extensions can cancel.
+	// Emit before-session-switch event in a goroutine so that extension
+	// handlers can call blocking operations (e.g. ctx.PromptConfirm) without
+	// deadlocking the BubbleTea event loop.
 	if m.emitBeforeSessionSwitch != nil {
-		if cancelled, reason := m.emitBeforeSessionSwitch("new"); cancelled {
-			return m.printSystemMessage(reason)
-		}
+		emit := m.emitBeforeSessionSwitch
+		ctrl := m.appCtrl
+		go func() {
+			cancelled, reason := emit("new")
+			ctrl.SendEvent(beforeSessionSwitchResultMsg{
+				cancelled: cancelled,
+				reason:    reason,
+			})
+		}()
+		return func() tea.Msg { return nil }
 	}
 
+	return m.performNewSession()
+}
+
+// performNewSession performs the actual session reset. Called either directly
+// (when no before-hook exists) or after the async hook completes.
+func (m *AppModel) performNewSession() tea.Cmd {
 	ts := m.appCtrl.GetTreeSession()
 	if ts == nil {
 		// No tree session — just clear messages.
@@ -2027,6 +2394,35 @@ func (m *AppModel) handleNewCommand() tea.Cmd {
 	return m.printSystemMessage("New branch started. Previous conversation is preserved in the tree.")
 }
 
+// performFork performs the actual tree branch. Called either directly (when no
+// before-hook exists) or after the async before-fork hook completes.
+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.")
+	}
+
+	_ = ts.Branch(targetID)
+	m.appCtrl.ClearMessages()
+
+	// If it was a user message, populate the input with the text.
+	if isUser && userText != "" {
+		if ic, ok := m.input.(*InputComponent); ok {
+			ic.textarea.SetValue(userText)
+			ic.textarea.CursorEnd()
+		}
+	}
+
+	return m.printSystemMessage(
+		fmt.Sprintf("Navigated to branch point. %s",
+			func() string {
+				if isUser {
+					return "Edit and resubmit to create a new branch."
+				}
+				return "Continue from this point."
+			}()))
+}
+
 // handleNameCommand sets a display name for the current session.
 func (m *AppModel) handleNameCommand() tea.Cmd {
 	ts := m.appCtrl.GetTreeSession()
@@ -2100,6 +2496,26 @@ type extensionCmdResultMsg struct {
 	err    error
 }
 
+// beforeSessionSwitchResultMsg carries the result of an asynchronously
+// executed before-session-switch hook. The hook runs in a goroutine so that
+// blocking operations like ctx.PromptConfirm() do not deadlock the TUI.
+type beforeSessionSwitchResultMsg struct {
+	cancelled bool
+	reason    string
+}
+
+// beforeForkResultMsg carries the result of an asynchronously executed
+// before-fork hook along with the fork context needed to complete the
+// operation if the hook allows it.
+type beforeForkResultMsg struct {
+	cancelled bool
+	reason    string
+	// Fork context — preserved so the operation can proceed after the hook.
+	targetID string
+	isUser   bool
+	userText string
+}
+
 // updatePromptState handles all messages while the prompt overlay is active.
 // It routes keys to the prompt overlay, detects completion/cancellation, and
 // restores the previous state when done.
@@ -2231,3 +2647,158 @@ func (m *AppModel) resolveOverlay(resp app.OverlayResponse) {
 	m.overlay = nil
 	m.state = m.preOverlayState
 }
+
+// --------------------------------------------------------------------------
+// Shell command execution (! and !!)
+// --------------------------------------------------------------------------
+
+// shellCommandTimeout is the maximum duration for a user shell command.
+const shellCommandTimeout = 120 * time.Second
+
+// executeShellCommand runs a shell command asynchronously and returns the
+// result as a shellCommandResultMsg. This is launched from Update() as a
+// tea.Cmd so the TUI stays responsive during execution.
+func (m *AppModel) executeShellCommand(msg shellCommandMsg) tea.Cmd {
+	command := msg.Command
+	excludeFromContext := msg.ExcludeFromContext
+	cwd := m.cwd
+
+	return func() tea.Msg {
+		ctx, cancel := context.WithTimeout(context.Background(), shellCommandTimeout)
+		defer cancel()
+
+		cmd := exec.CommandContext(ctx, "bash", "-c", command)
+		if cwd != "" {
+			cmd.Dir = cwd
+		}
+
+		var stdout, stderr bytes.Buffer
+		cmd.Stdout = &stdout
+		cmd.Stderr = &stderr
+
+		err := cmd.Run()
+
+		exitCode := 0
+		if err != nil {
+			if exitErr, ok := err.(*exec.ExitError); ok {
+				exitCode = exitErr.ExitCode()
+				// Non-zero exit is reported via exitCode, not as an error.
+				err = nil
+			} else if ctx.Err() == context.DeadlineExceeded {
+				return shellCommandResultMsg{
+					Command:            command,
+					Output:             fmt.Sprintf("command timed out after %v", shellCommandTimeout),
+					ExitCode:           -1,
+					Err:                fmt.Errorf("command timed out after %v", shellCommandTimeout),
+					ExcludeFromContext: excludeFromContext,
+				}
+			}
+		}
+
+		// Combine stdout + stderr.
+		var combined strings.Builder
+		if stdout.Len() > 0 {
+			combined.WriteString(stdout.String())
+		}
+		if stderr.Len() > 0 {
+			if combined.Len() > 0 {
+				combined.WriteString("\n")
+			}
+			combined.WriteString(stderr.String())
+		}
+
+		return shellCommandResultMsg{
+			Command:            command,
+			Output:             combined.String(),
+			ExitCode:           exitCode,
+			Err:                err,
+			ExcludeFromContext: excludeFromContext,
+		}
+	}
+}
+
+// handleShellCommandResult processes the result of a shell command execution.
+// It prints the output to scrollback and optionally injects it into the
+// conversation context (for ! commands) so the LLM can see it.
+func (m *AppModel) handleShellCommandResult(msg shellCommandResultMsg) tea.Cmd {
+	theme := GetTheme()
+
+	// Build the display header.
+	var header string
+	if msg.ExcludeFromContext {
+		header = fmt.Sprintf("$ %s  (excluded from context)", msg.Command)
+	} else {
+		header = fmt.Sprintf("$ %s", msg.Command)
+	}
+
+	// Build the output content.
+	var content strings.Builder
+	content.WriteString(header)
+
+	// Display-level truncation: show first maxShellDisplayLines lines with a
+	// "...(N more lines)" hint, matching the tool result renderer behavior.
+	const maxShellDisplayLines = 20
+
+	displayOutput := msg.Output
+	var displayHiddenCount int
+	if displayOutput != "" {
+		lines := strings.Split(displayOutput, "\n")
+		if len(lines) > maxShellDisplayLines {
+			displayHiddenCount = len(lines) - maxShellDisplayLines
+			displayOutput = strings.Join(lines[:maxShellDisplayLines], "\n")
+		}
+	}
+
+	if msg.Err != nil {
+		fmt.Fprintf(&content, "\n\nError: %v", msg.Err)
+	} else if displayOutput != "" {
+		content.WriteString("\n\n")
+		content.WriteString(displayOutput)
+		if displayHiddenCount > 0 {
+			fmt.Fprintf(&content, "\n\n...(%d more lines)", displayHiddenCount)
+		}
+	} else {
+		content.WriteString("\n\n(no output)")
+	}
+
+	if msg.ExitCode != 0 {
+		fmt.Fprintf(&content, "\n\nExit code: %d", msg.ExitCode)
+	}
+
+	// Choose border color: dim for excluded, accent for included.
+	borderClr := theme.Accent
+	if msg.ExcludeFromContext {
+		borderClr = theme.Muted
+	}
+
+	rendered := renderContentBlock(
+		content.String(),
+		m.width,
+		WithAlign(lipgloss.Left),
+		WithBorderColor(borderClr),
+		WithMarginBottom(1),
+	)
+
+	var cmds []tea.Cmd
+	cmds = append(cmds, tea.Println(rendered))
+
+	// For ! (included in context): inject the command output into the
+	// conversation as a user message so the LLM can reference it on the
+	// next turn. This does NOT trigger an LLM response — it only adds
+	// to the conversation history.
+	if !msg.ExcludeFromContext && m.appCtrl != nil {
+		// Truncate context output with the same limits as display.
+		contextOutput := msg.Output
+		if contextOutput != "" {
+			tr := core.TruncateTail(contextOutput, core.DefaultMaxLines, core.DefaultMaxBytes)
+			contextOutput = tr.Content
+		} else {
+			contextOutput = "(no output)"
+		}
+		contextMsg := fmt.Sprintf("<shell_command>\n<command>%s</command>\n<output>\n%s</output>\n<exit_code>%d</exit_code>\n</shell_command>",
+			msg.Command, contextOutput, msg.ExitCode)
+		m.appCtrl.AddContextMessage(contextMsg)
+	}
+
+	return tea.Batch(cmds...)
+}

internal/ui/model_selector.go

@@ -0,0 +1,413 @@
+package ui
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"charm.land/bubbles/v2/key"
+	tea "charm.land/bubbletea/v2"
+	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/models"
+)
+
+// ModelEntry holds display metadata for a single model in the selector.
+type ModelEntry struct {
+	Provider     string
+	ModelID      string
+	Name         string // human-friendly name (e.g. "Claude Haiku 4.5")
+	ContextLimit int
+	Reasoning    bool
+}
+
+// ModelSelectedMsg is sent when the user selects a model from the selector.
+type ModelSelectedMsg struct {
+	ModelString string // "provider/model-id"
+}
+
+// ModelSelectorCancelledMsg is sent when the user cancels the selector.
+type ModelSelectorCancelledMsg struct{}
+
+// ModelSelectorComponent is a full-screen Bubble Tea component that displays
+// a filterable list of available models. It follows the same pattern as
+// TreeSelectorComponent: inline text search, scrolling list, and custom
+// messages for result delivery.
+type ModelSelectorComponent struct {
+	allModels    []ModelEntry // all available models (pre-sorted)
+	filtered     []ModelEntry // subset matching the current search
+	cursor       int
+	search       string
+	currentModel string // "provider/model" of the active model (for checkmark)
+	width        int
+	height       int
+	active       bool
+}
+
+// NewModelSelector creates a model selector populated from the global registry,
+// filtered to only providers with configured API keys.
+func NewModelSelector(currentModel string, width, height int) *ModelSelectorComponent {
+	registry := models.GetGlobalRegistry()
+	var allModels []ModelEntry
+
+	for _, providerID := range registry.GetFantasyProviders() {
+		// Only include providers with valid API keys configured.
+		if err := registry.ValidateEnvironment(providerID, ""); err != nil {
+			continue
+		}
+
+		modelsMap, err := registry.GetModelsForProvider(providerID)
+		if err != nil {
+			continue
+		}
+
+		for modelID, info := range modelsMap {
+			allModels = append(allModels, ModelEntry{
+				Provider:     providerID,
+				ModelID:      modelID,
+				Name:         info.Name,
+				ContextLimit: info.Limit.Context,
+				Reasoning:    info.Reasoning,
+			})
+		}
+	}
+
+	// Sort: alphabetically by model ID, grouped by provider.
+	sort.Slice(allModels, func(i, j int) bool {
+		if allModels[i].Provider != allModels[j].Provider {
+			return allModels[i].Provider < allModels[j].Provider
+		}
+		return allModels[i].ModelID < allModels[j].ModelID
+	})
+
+	ms := &ModelSelectorComponent{
+		allModels:    allModels,
+		filtered:     allModels,
+		currentModel: currentModel,
+		width:        width,
+		height:       height,
+		active:       true,
+	}
+
+	// Position cursor on the current model if found.
+	for i, m := range ms.filtered {
+		if m.Provider+"/"+m.ModelID == currentModel {
+			ms.cursor = i
+			break
+		}
+	}
+
+	return ms
+}
+
+// Init implements tea.Model.
+func (ms *ModelSelectorComponent) Init() tea.Cmd {
+	return nil
+}
+
+// Update implements tea.Model.
+func (ms *ModelSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	switch msg := msg.(type) {
+	case tea.WindowSizeMsg:
+		ms.width = msg.Width
+		ms.height = msg.Height
+		return ms, nil
+
+	case tea.KeyPressMsg:
+		switch {
+		case key.Matches(msg, key.NewBinding(key.WithKeys("up", "k"))):
+			if ms.cursor > 0 {
+				ms.cursor--
+			}
+
+		case key.Matches(msg, key.NewBinding(key.WithKeys("down", "j"))):
+			if ms.cursor < len(ms.filtered)-1 {
+				ms.cursor++
+			}
+
+		case key.Matches(msg, key.NewBinding(key.WithKeys("pgup"))):
+			ms.cursor -= ms.visibleHeight()
+			if ms.cursor < 0 {
+				ms.cursor = 0
+			}
+
+		case key.Matches(msg, key.NewBinding(key.WithKeys("pgdown"))):
+			ms.cursor += ms.visibleHeight()
+			if ms.cursor >= len(ms.filtered) {
+				ms.cursor = len(ms.filtered) - 1
+			}
+			if ms.cursor < 0 {
+				ms.cursor = 0
+			}
+
+		case key.Matches(msg, key.NewBinding(key.WithKeys("home"))):
+			ms.cursor = 0
+
+		case key.Matches(msg, key.NewBinding(key.WithKeys("end"))):
+			ms.cursor = max(len(ms.filtered)-1, 0)
+
+		case key.Matches(msg, key.NewBinding(key.WithKeys("enter"))):
+			if ms.cursor < len(ms.filtered) {
+				entry := ms.filtered[ms.cursor]
+				ms.active = false
+				return ms, func() tea.Msg {
+					return ModelSelectedMsg{
+						ModelString: entry.Provider + "/" + entry.ModelID,
+					}
+				}
+			}
+
+		case key.Matches(msg, key.NewBinding(key.WithKeys("esc"))):
+			if ms.search != "" {
+				ms.search = ""
+				ms.rebuildFiltered()
+			} else {
+				ms.active = false
+				return ms, func() tea.Msg {
+					return ModelSelectorCancelledMsg{}
+				}
+			}
+
+		default:
+			// Inline text search.
+			if msg.Text != "" && len(msg.Text) == 1 {
+				ch := msg.Text[0]
+				if ch >= 32 && ch < 127 {
+					ms.search += string(ch)
+					ms.rebuildFiltered()
+				}
+			}
+			if key.Matches(msg, key.NewBinding(key.WithKeys("backspace"))) && len(ms.search) > 0 {
+				ms.search = ms.search[:len(ms.search)-1]
+				ms.rebuildFiltered()
+			}
+		}
+	}
+	return ms, nil
+}
+
+// View implements tea.Model.
+func (ms *ModelSelectorComponent) View() tea.View {
+	theme := GetTheme()
+
+	headerStyle := lipgloss.NewStyle().
+		Bold(true).
+		Foreground(theme.Accent).
+		PaddingLeft(2)
+
+	helpStyle := lipgloss.NewStyle().
+		Foreground(theme.Muted).
+		PaddingLeft(2)
+
+	infoStyle := lipgloss.NewStyle().
+		Foreground(theme.Warning).
+		PaddingLeft(2)
+
+	var b strings.Builder
+
+	// Header.
+	b.WriteString(headerStyle.Render("Model Selector"))
+	b.WriteString("\n")
+	b.WriteString(helpStyle.Render("↑/↓: move  enter: select  esc: cancel  type to filter"))
+	b.WriteString("\n")
+	b.WriteString(infoStyle.Render("Only showing models with configured API keys"))
+	b.WriteString("\n")
+
+	// Search input.
+	searchStyle := lipgloss.NewStyle().Foreground(theme.Info).PaddingLeft(2)
+	if ms.search != "" {
+		b.WriteString(searchStyle.Render(fmt.Sprintf("> %s", ms.search)))
+	} else {
+		b.WriteString(searchStyle.Render("> "))
+	}
+	b.WriteString("\n")
+
+	b.WriteString(lipgloss.NewStyle().Foreground(theme.Muted).Render(strings.Repeat("─", ms.width)))
+	b.WriteString("\n")
+
+	if len(ms.filtered) == 0 {
+		emptyStyle := lipgloss.NewStyle().Foreground(theme.Muted).PaddingLeft(2)
+		if ms.search != "" {
+			b.WriteString(emptyStyle.Render("No models matching \"" + ms.search + "\""))
+		} else {
+			b.WriteString(emptyStyle.Render("No models available (check API keys)"))
+		}
+		b.WriteString("\n")
+	} else {
+		// Visible window.
+		visH := ms.visibleHeight()
+		startIdx := 0
+		if ms.cursor >= visH {
+			startIdx = ms.cursor - visH + 1
+		}
+		endIdx := min(startIdx+visH, len(ms.filtered))
+
+		for i := startIdx; i < endIdx; i++ {
+			entry := ms.filtered[i]
+			line := ms.renderEntry(entry, i == ms.cursor)
+			b.WriteString(line)
+			b.WriteString("\n")
+		}
+	}
+
+	// Footer.
+	b.WriteString(lipgloss.NewStyle().Foreground(theme.Muted).Render(strings.Repeat("─", ms.width)))
+	b.WriteString("\n")
+
+	footerParts := []string{
+		fmt.Sprintf("(%d/%d)", ms.cursor+1, len(ms.filtered)),
+	}
+	if ms.cursor < len(ms.filtered) {
+		entry := ms.filtered[ms.cursor]
+		if entry.Name != "" {
+			footerParts = append(footerParts, fmt.Sprintf("Model Name: %s", entry.Name))
+		}
+		if entry.ContextLimit > 0 {
+			footerParts = append(footerParts, fmt.Sprintf("Context: %dK", entry.ContextLimit/1000))
+		}
+	}
+
+	footerStyle := lipgloss.NewStyle().Foreground(theme.Muted).PaddingLeft(2)
+	b.WriteString(footerStyle.Render(strings.Join(footerParts, "  ")))
+
+	return tea.NewView(b.String())
+}
+
+// IsActive returns whether the selector is still accepting input.
+func (ms *ModelSelectorComponent) IsActive() bool {
+	return ms.active
+}
+
+// --- Internal helpers ---
+
+func (ms *ModelSelectorComponent) visibleHeight() int {
+	// Reserve: header(1) + help(1) + info(1) + search(1) + separator(1) + footer(2) = 7
+	h := max(ms.height-7, 5)
+	return h
+}
+
+func (ms *ModelSelectorComponent) rebuildFiltered() {
+	if ms.search == "" {
+		ms.filtered = ms.allModels
+	} else {
+		query := strings.ToLower(ms.search)
+		ms.filtered = ms.filtered[:0]
+
+		type scored struct {
+			entry ModelEntry
+			score int
+		}
+		var matches []scored
+
+		for _, entry := range ms.allModels {
+			s := ms.fuzzyScoreModel(query, entry)
+			if s > 0 {
+				matches = append(matches, scored{entry: entry, score: s})
+			}
+		}
+
+		// Sort by score descending, then alphabetically.
+		sort.Slice(matches, func(i, j int) bool {
+			if matches[i].score != matches[j].score {
+				return matches[i].score > matches[j].score
+			}
+			return matches[i].entry.ModelID < matches[j].entry.ModelID
+		})
+
+		ms.filtered = make([]ModelEntry, len(matches))
+		for i, m := range matches {
+			ms.filtered[i] = m.entry
+		}
+	}
+
+	// Clamp cursor.
+	if ms.cursor >= len(ms.filtered) {
+		ms.cursor = max(len(ms.filtered)-1, 0)
+	}
+}
+
+// fuzzyScoreModel scores a model entry against the search query.
+func (ms *ModelSelectorComponent) fuzzyScoreModel(query string, entry ModelEntry) int {
+	modelID := strings.ToLower(entry.ModelID)
+	provider := strings.ToLower(entry.Provider)
+	name := strings.ToLower(entry.Name)
+	combined := provider + "/" + modelID
+
+	// Exact match on combined provider/model.
+	if combined == query {
+		return 1000
+	}
+
+	// Exact match on model ID.
+	if modelID == query {
+		return 950
+	}
+
+	// Prefix match on model ID.
+	if strings.HasPrefix(modelID, query) {
+		return 800 - len(modelID) + len(query)
+	}
+
+	// Prefix match on combined.
+	if strings.HasPrefix(combined, query) {
+		return 750 - len(combined) + len(query)
+	}
+
+	// Contains match on model ID.
+	if strings.Contains(modelID, query) {
+		return 600
+	}
+
+	// Contains match on combined.
+	if strings.Contains(combined, query) {
+		return 550
+	}
+
+	// Contains match on name.
+	if strings.Contains(name, query) {
+		return 400
+	}
+
+	// Character-by-character fuzzy match on model ID.
+	if s := fuzzyCharacterMatch(query, modelID); s > 0 {
+		return s
+	}
+
+	// Fuzzy match on combined.
+	if s := fuzzyCharacterMatch(query, combined); s > 0 {
+		return s - 20
+	}
+
+	return 0
+}
+
+func (ms *ModelSelectorComponent) renderEntry(entry ModelEntry, isCursor bool) string {
+	theme := GetTheme()
+	modelStr := entry.ModelID
+	providerStr := fmt.Sprintf("[%s]", entry.Provider)
+
+	// Cursor indicator.
+	var cursor string
+	if isCursor {
+		cursor = lipgloss.NewStyle().Foreground(theme.Accent).Render("-> ")
+	} else {
+		cursor = "   "
+	}
+
+	// Active model checkmark.
+	var active string
+	if entry.Provider+"/"+entry.ModelID == ms.currentModel {
+		active = lipgloss.NewStyle().Foreground(theme.Success).Render(" \u2713")
+	}
+
+	// Style the model ID.
+	modelStyle := lipgloss.NewStyle().Foreground(theme.Text)
+	if isCursor {
+		modelStyle = modelStyle.Bold(true).Foreground(theme.Accent)
+	}
+
+	// Style the provider tag.
+	providerStyle := lipgloss.NewStyle().Foreground(theme.Muted)
+
+	return cursor + modelStyle.Render(modelStr) + " " + providerStyle.Render(providerStr) + active
+}

internal/ui/model_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	tea "charm.land/bubbletea/v2"
+	"charm.land/fantasy"
 	"github.com/mark3labs/kit/internal/app"
 	"github.com/mark3labs/kit/internal/session"
 )
@@ -57,6 +58,15 @@ func (s *stubAppController) SendEvent(_ tea.Msg) {
 	// no-op in tests
 }
 
+func (s *stubAppController) AddContextMessage(_ string) {
+	// no-op in tests
+}
+
+func (s *stubAppController) RunWithFiles(prompt string, _ []fantasy.FilePart) int {
+	s.runCalls = append(s.runCalls, prompt)
+	return s.queueLen
+}
+
 // --------------------------------------------------------------------------
 // Stub child components
 // --------------------------------------------------------------------------
@@ -79,6 +89,8 @@ func (s *stubStreamComponent) Reset()                     { s.resetCalled++; s.r
 func (s *stubStreamComponent) SetHeight(h int)            { s.height = h }
 func (s *stubStreamComponent) GetRenderedContent() string { return s.renderedContent }
 func (s *stubStreamComponent) SpinnerView() string        { return "" }
+func (s *stubStreamComponent) SetThinkingVisible(bool)    {}
+func (s *stubStreamComponent) HasReasoning() bool         { return false }
 
 // stubInputComponent satisfies inputComponentIface without rendering anything.
 type stubInputComponent struct {

internal/ui/stream.go

@@ -69,6 +69,25 @@ func streamSpinnerTickCmd() tea.Cmd {
 	})
 }
 
+// streamFlushTickMsg fires when it's time to commit pending chunks to the
+// main content builders and trigger a re-render. This coalesces rapid
+// streaming chunks into fewer expensive markdown re-renders.
+type streamFlushTickMsg struct{}
+
+// streamFlushInterval is the coalescing window for stream chunks. Chunks
+// arriving within this window are batched into a single render pass.
+// 16ms ≈ 60 fps — fast enough to appear smooth, slow enough to coalesce
+// bursts from the LLM provider.
+const streamFlushInterval = 16 * time.Millisecond
+
+// streamFlushTickCmd returns a tea.Cmd that fires streamFlushTickMsg after
+// the coalescing interval.
+func streamFlushTickCmd() tea.Cmd {
+	return tea.Tick(streamFlushInterval, func(_ time.Time) tea.Msg {
+		return streamFlushTickMsg{}
+	})
+}
+
 // streamPhase tracks what the StreamComponent is currently displaying.
 type streamPhase int
 
@@ -114,13 +133,41 @@ type StreamComponent struct {
 	// spinnerFrame is the current frame index.
 	spinnerFrame int
 
-	// spinnerMsg is the label shown next to the KITT animation (e.g.
-	// "Executing tool_name…"). Empty string means no label.
-	spinnerMsg string
+	// activeTools tracks the names of tools currently executing in parallel.
+	// When multiple tools run concurrently, all are displayed in the spinner.
+	activeTools []string
 
-	// streamContent accumulates all streaming text chunks.
+	// streamContent holds committed streaming text (flushed from pending).
 	streamContent strings.Builder
 
+	// reasoningContent holds committed reasoning text (flushed from pending).
+	reasoningContent strings.Builder
+
+	// pendingStream accumulates streaming text chunks between flush ticks.
+	// Chunks are written here immediately on arrival, then moved to
+	// streamContent when the flush tick fires.
+	pendingStream strings.Builder
+
+	// pendingReasoning accumulates reasoning chunks between flush ticks.
+	pendingReasoning strings.Builder
+
+	// flushPending is true while a flush tick is in-flight. Prevents
+	// scheduling duplicate ticks when multiple chunks arrive within
+	// the same coalescing window.
+	flushPending bool
+
+	// renderCache holds the last rendered output string. Reused by View()
+	// between flush ticks to avoid redundant markdown re-parsing.
+	renderCache string
+
+	// renderDirty is true when committed content has changed since the
+	// last render. Set on flush tick; cleared after render() rebuilds
+	// the cache.
+	renderDirty bool
+
+	// thinkingVisible controls whether reasoning blocks are shown or collapsed.
+	thinkingVisible bool
+
 	// messageRenderer renders assistant messages in standard mode.
 	messageRenderer *MessageRenderer
 
@@ -166,7 +213,12 @@ func (s *StreamComponent) SetHeight(h int) {
 	if h < 0 {
 		h = 0
 	}
-	s.height = h
+	if s.height != h {
+		s.height = h
+		// Invalidate cache — height clamp affects output.
+		s.renderCache = ""
+		s.renderDirty = true
+	}
 }
 
 // Reset clears all accumulated state so the component is ready for the next
@@ -175,20 +227,58 @@ func (s *StreamComponent) Reset() {
 	s.phase = streamPhaseIdle
 	s.spinning = false
 	s.spinnerFrame = 0
-	s.spinnerMsg = ""
+	s.activeTools = nil
 	s.streamContent.Reset()
+	s.reasoningContent.Reset()
+	s.pendingStream.Reset()
+	s.pendingReasoning.Reset()
+	s.flushPending = false
+	s.renderCache = ""
+	s.renderDirty = false
 	s.timestamp = time.Time{}
 }
 
 // GetRenderedContent returns the rendered assistant message from the accumulated
 // streaming text. Returns empty string if no text has been accumulated. Used by
 // the parent AppModel to flush content via tea.Println() before resetting.
+//
+// This commits any pending chunks first so the output includes all received
+// content, not just what has been flushed by the tick.
 func (s *StreamComponent) GetRenderedContent() string {
+	// Commit any pending chunks so the final output is complete.
+	s.commitPending()
+
+	var sections []string
+
+	// Include rendered reasoning block if present.
+	if reasoning := s.reasoningContent.String(); reasoning != "" {
+		sections = append(sections, s.renderReasoningBlock(reasoning))
+	}
+
 	text := s.streamContent.String()
-	if text == "" {
+	if text != "" {
+		sections = append(sections, s.renderStreamingText(text))
+	}
+
+	if len(sections) == 0 {
 		return ""
 	}
-	return s.renderStreamingText(text)
+	return strings.Join(sections, "\n")
+}
+
+// commitPending moves any pending chunks to the committed content builders.
+// Called before reading content for scrollback output or on flush tick.
+func (s *StreamComponent) commitPending() {
+	if s.pendingStream.Len() > 0 {
+		s.streamContent.WriteString(s.pendingStream.String())
+		s.pendingStream.Reset()
+		s.renderDirty = true
+	}
+	if s.pendingReasoning.Len() > 0 {
+		s.reasoningContent.WriteString(s.pendingReasoning.String())
+		s.pendingReasoning.Reset()
+		s.renderDirty = true
+	}
 }
 
 // --------------------------------------------------------------------------
@@ -209,6 +299,9 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		s.width = msg.Width
 		s.messageRenderer.SetWidth(s.width)
 		s.compactRenderer.SetWidth(s.width)
+		// Invalidate render cache — width change affects wrapping/styling.
+		s.renderCache = ""
+		s.renderDirty = true
 
 	case streamSpinnerTickMsg:
 		if s.spinning {
@@ -228,6 +321,23 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				s.timestamp = time.Now()
 			}
 			return s, streamSpinnerTickCmd()
+		} else if !msg.Show && s.spinning {
+			s.spinning = false
+		}
+
+	case streamFlushTickMsg:
+		s.flushPending = false
+		s.commitPending()
+
+	case app.ReasoningChunkEvent:
+		s.phase = streamPhaseActive
+		if s.timestamp.IsZero() {
+			s.timestamp = time.Now()
+		}
+		s.pendingReasoning.WriteString(msg.Delta)
+		if !s.flushPending {
+			s.flushPending = true
+			return s, streamFlushTickCmd()
 		}
 
 	case app.StreamChunkEvent:
@@ -235,12 +345,17 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if s.timestamp.IsZero() {
 			s.timestamp = time.Now()
 		}
-		s.streamContent.WriteString(msg.Content)
+		s.pendingStream.WriteString(msg.Content)
+		if !s.flushPending {
+			s.flushPending = true
+			return s, streamFlushTickCmd()
+		}
 
 	case app.ToolExecutionEvent:
 		if msg.IsStarting {
-			// Show the tool name on the spinner while the tool executes.
-			s.spinnerMsg = "Executing " + msg.ToolName + "…"
+			// Add tool to active list for parallel execution display.
+			toolDisplay := formatToolExecutionMessage(msg.ToolName, msg.ToolArgs)
+			s.activeTools = append(s.activeTools, toolDisplay)
 			s.spinnerFrame = 0
 			if !s.spinning {
 				s.phase = streamPhaseActive
@@ -248,8 +363,9 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				return s, streamSpinnerTickCmd()
 			}
 		} else {
-			// Tool finished — clear execution label but keep spinning.
-			s.spinnerMsg = ""
+			// Tool finished — remove from active list but keep spinning if others remain.
+			toolDisplay := formatToolExecutionMessage(msg.ToolName, msg.ToolArgs)
+			s.activeTools = removeFromSlice(s.activeTools, toolDisplay)
 		}
 	}
 
@@ -265,20 +381,41 @@ func (s *StreamComponent) View() tea.View {
 // Internal rendering
 // --------------------------------------------------------------------------
 
-// render builds the full content string for the stream region.
+// render builds the full content string for the stream region. Uses a render
+// cache to avoid redundant markdown re-parsing between flush ticks. The cache
+// is invalidated when committed content changes (flush tick), terminal width
+// changes, or height/thinking visibility changes.
 func (s *StreamComponent) render() string {
 	if s.phase == streamPhaseIdle {
 		return ""
 	}
 
+	// Return cached render if committed content hasn't changed.
+	if !s.renderDirty {
+		return s.renderCache
+	}
+
+	var sections []string
+
+	// Render reasoning/thinking block above the main text if present.
+	if reasoning := s.reasoningContent.String(); reasoning != "" {
+		sections = append(sections, s.renderReasoningBlock(reasoning))
+	}
+
 	// Render streaming text only. The spinner is rendered in the status bar
 	// by the parent so it never changes the stream region height.
 	text := s.streamContent.String()
-	if text == "" {
+	if text != "" {
+		sections = append(sections, s.renderStreamingText(text))
+	}
+
+	if len(sections) == 0 {
+		s.renderCache = ""
+		s.renderDirty = false
 		return ""
 	}
 
-	content := s.renderStreamingText(text)
+	content := strings.Join(sections, "\n")
 
 	// Clamp to height if constrained: keep the last h lines so the most
 	// recent output is always visible.
@@ -290,9 +427,52 @@ func (s *StreamComponent) render() string {
 		}
 	}
 
+	s.renderCache = content
+	s.renderDirty = false
 	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.
+func (s *StreamComponent) renderReasoningBlock(reasoning string) string {
+	theme := GetTheme()
+
+	if !s.thinkingVisible {
+		// Show collapsed "Thinking..." label.
+		return lipgloss.NewStyle().
+			Foreground(theme.Muted).
+			Italic(true).
+			Render("Thinking...")
+	}
+
+	// Render full reasoning text in muted italic style.
+	style := 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
+}
+
+// SetThinkingVisible sets whether reasoning blocks are shown or collapsed.
+func (s *StreamComponent) SetThinkingVisible(visible bool) {
+	if s.thinkingVisible != visible {
+		s.thinkingVisible = visible
+		// Invalidate cache — thinking visibility affects rendered output.
+		s.renderCache = ""
+		s.renderDirty = true
+	}
+}
+
+// HasReasoning returns true if any reasoning content has been accumulated
+// (committed or pending).
+func (s *StreamComponent) HasReasoning() bool {
+	return s.reasoningContent.Len() > 0 || s.pendingReasoning.Len() > 0
+}
+
 // SpinnerView returns the rendered spinner line for the parent to embed in the
 // status bar. Returns "" when the spinner is not active.
 func (s *StreamComponent) SpinnerView() string {
@@ -300,14 +480,22 @@ func (s *StreamComponent) SpinnerView() string {
 		return ""
 	}
 	frame := s.spinnerFrames[s.spinnerFrame%len(s.spinnerFrames)]
-	if s.spinnerMsg == "" {
+	if len(s.activeTools) == 0 {
 		return "  " + frame
 	}
 	theme := GetTheme()
 	msgStyle := lipgloss.NewStyle().
 		Foreground(theme.Text).
 		Italic(true)
-	return "  " + frame + " " + msgStyle.Render(s.spinnerMsg)
+
+	// Format active tools list
+	var toolsMsg string
+	if len(s.activeTools) == 1 {
+		toolsMsg = s.activeTools[0]
+	} else {
+		toolsMsg = "Running: " + strings.Join(s.activeTools, ", ")
+	}
+	return "  " + frame + " " + msgStyle.Render(toolsMsg)
 }
 
 // renderStreamingText renders the accumulated streaming text as a live assistant
@@ -325,3 +513,22 @@ func (s *StreamComponent) renderStreamingText(text string) string {
 	msg := s.messageRenderer.RenderAssistantMessage(text, ts, s.modelName)
 	return msg.Content
 }
+
+// removeFromSlice removes the first occurrence of a string from a slice.
+func removeFromSlice(slice []string, s string) []string {
+	for i, v := range slice {
+		if v == s {
+			return append(slice[:i], slice[i+1:]...)
+		}
+	}
+	return slice
+}
+
+// formatToolExecutionMessage creates a descriptive spinner message for tool execution.
+// For spawn_subagent, it shows simply as "Subagent" with optional task preview.
+func formatToolExecutionMessage(toolName, toolArgs string) string {
+	if toolName == "spawn_subagent" {
+		return "Subagent"
+	}
+	return toolName
+}

internal/ui/tool_renderers.go

@@ -49,6 +49,10 @@ func renderToolBody(toolName, toolArgs, toolResult string, width int) string {
 		if body := renderBashBody(toolResult, width); body != "" {
 			return body
 		}
+	case toolName == "spawn_subagent":
+		if body := renderSubagentBody(toolResult, width); body != "" {
+			return body
+		}
 	}
 	return "" // fall back to default
 }
@@ -716,6 +720,8 @@ func renderToolBodyCompact(toolName, toolArgs, toolResult string, width int) str
 	case toolName == "bash" || toolName == "run_shell_cmd" ||
 		strings.Contains(toolName, "shell") || strings.Contains(toolName, "command"):
 		return renderBashCompact(toolResult, width)
+	case toolName == "spawn_subagent":
+		return renderSubagentCompact(toolResult)
 	}
 	return ""
 }
@@ -870,3 +876,121 @@ func renderBashCompact(toolResult string, width int) string {
 
 	return lipgloss.NewStyle().Foreground(theme.Muted).Render(summary)
 }
+
+// ---------------------------------------------------------------------------
+// Subagent tool renderers — show only summary, not full output
+// ---------------------------------------------------------------------------
+
+// renderSubagentBody renders a clean summary of subagent results.
+// Extracts timing/token info and shows only a brief summary instead of raw output.
+func renderSubagentBody(toolResult string, width int) string {
+	theme := getTheme()
+	result := strings.TrimSpace(toolResult)
+	if result == "" {
+		return ""
+	}
+
+	// Parse the subagent result format:
+	// "Subagent completed successfully in Xs. (tokens: N in / M out)\n\nResult:\n..."
+	// or "Subagent failed (exit code X) after Ys.\n\nError: ...\n\nPartial output:\n..."
+
+	lines := strings.Split(result, "\n")
+	if len(lines) == 0 {
+		return ""
+	}
+
+	// First line is always the status summary
+	statusLine := lines[0]
+
+	// Build a clean summary
+	var summary strings.Builder
+	summary.WriteString(lipgloss.NewStyle().Foreground(theme.Muted).Render(statusLine))
+
+	// For successful results, extract a brief preview of the actual result
+	if strings.Contains(statusLine, "successfully") {
+		// Find where "Result:" starts and extract a preview
+		if _, resultContent, found := strings.Cut(result, "Result:\n"); found {
+			resultContent = strings.TrimSpace(resultContent)
+			if resultContent != "" {
+				// Show first 3 meaningful lines as preview
+				preview := extractSubagentPreview(resultContent, 3, width-4)
+				if preview != "" {
+					summary.WriteString("\n\n")
+					summary.WriteString(lipgloss.NewStyle().
+						Foreground(theme.Muted).
+						Italic(true).
+						Render(preview))
+				}
+			}
+		}
+	}
+
+	return summary.String()
+}
+
+// extractSubagentPreview extracts the first N non-empty lines from content,
+// truncating each line to maxWidth.
+func extractSubagentPreview(content string, maxLines, maxWidth int) string {
+	lines := strings.Split(content, "\n")
+	var preview []string
+
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" {
+			continue
+		}
+
+		// Truncate long lines
+		if len(trimmed) > maxWidth {
+			trimmed = trimmed[:maxWidth-3] + "..."
+		}
+		preview = append(preview, trimmed)
+
+		if len(preview) >= maxLines {
+			break
+		}
+	}
+
+	if len(preview) == 0 {
+		return ""
+	}
+
+	result := strings.Join(preview, "\n")
+
+	// Count remaining lines for "more" indicator
+	totalLines := 0
+	for _, line := range lines {
+		if strings.TrimSpace(line) != "" {
+			totalLines++
+		}
+	}
+	if totalLines > maxLines {
+		result += fmt.Sprintf("\n...(%d more lines)", totalLines-maxLines)
+	}
+
+	return result
+}
+
+// renderSubagentCompact returns a brief one-line summary for subagent results.
+func renderSubagentCompact(toolResult string) string {
+	result := strings.TrimSpace(toolResult)
+	if result == "" {
+		return ""
+	}
+
+	theme := getTheme()
+
+	// Extract just the first line which contains the status
+	lines := strings.Split(result, "\n")
+	if len(lines) == 0 {
+		return ""
+	}
+
+	statusLine := lines[0]
+
+	// Make it more compact by removing redundant words
+	statusLine = strings.Replace(statusLine, "Subagent completed successfully in ", "Completed in ", 1)
+	statusLine = strings.Replace(statusLine, "Subagent failed", "Failed", 1)
+
+	return lipgloss.NewStyle().Foreground(theme.Muted).Italic(true).Render(statusLine)
+}

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/config.go

@@ -45,6 +45,7 @@ func setSDKDefaults() {
 	viper.SetDefault("top-p", 0.95)
 	viper.SetDefault("top-k", 40)
 	viper.SetDefault("stream", true)
+	viper.SetDefault("thinking-level", "off")
 	viper.SetDefault("num-gpu-layers", -1)
 	viper.SetDefault("main-gpu", 0)
 }

pkg/kit/events.go

@@ -1,6 +1,9 @@
 package kit
 
-import "sync"
+import (
+	"encoding/json"
+	"sync"
+)
 
 // ---------------------------------------------------------------------------
 // Event types
@@ -34,6 +37,8 @@ const (
 	EventResponse EventType = "response"
 	// EventCompaction fires after a successful compaction.
 	EventCompaction EventType = "compaction"
+	// EventReasoningDelta fires for each streaming reasoning/thinking chunk.
+	EventReasoningDelta EventType = "reasoning_delta"
 )
 
 // ---------------------------------------------------------------------------
@@ -46,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
 // ---------------------------------------------------------------------------
@@ -60,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.
@@ -81,6 +135,14 @@ type MessageUpdateEvent struct {
 // EventType implements Event.
 func (e MessageUpdateEvent) EventType() EventType { return EventMessageUpdate }
 
+// ReasoningDeltaEvent fires for each streaming reasoning/thinking chunk.
+type ReasoningDeltaEvent struct {
+	Delta string
+}
+
+// EventType implements Event.
+func (e ReasoningDeltaEvent) EventType() EventType { return EventReasoningDelta }
+
 // MessageEndEvent fires when the assistant message is complete.
 type MessageEndEvent struct {
 	Content string
@@ -91,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.
@@ -100,7 +165,10 @@ func (e ToolCallEvent) EventType() EventType { return EventToolCall }
 
 // ToolExecutionStartEvent fires when a tool begins executing.
 type ToolExecutionStartEvent struct {
-	ToolName string
+	ToolCallID string
+	ToolName   string
+	ToolKind   string
+	ToolArgs   string
 }
 
 // EventType implements Event.
@@ -108,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.
@@ -116,10 +186,34 @@ 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
+}
+
+// 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

@@ -1,6 +1,8 @@
 package kit
 
 import (
+	"strings"
+
 	"charm.land/fantasy"
 	"github.com/mark3labs/kit/internal/extensions"
 )
@@ -87,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,
@@ -109,16 +113,16 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 			extMsgs := make([]extensions.ContextMessage, len(h.Messages))
 			for i, msg := range h.Messages {
 				// Extract text from content parts.
-				var text string
+				var text strings.Builder
 				for _, part := range msg.Content {
 					if tp, ok := part.(fantasy.TextPart); ok {
-						text += tp.Text
+						text.WriteString(tp.Text)
 					}
 				}
 				extMsgs[i] = extensions.ContextMessage{
 					Index:   i,
 					Role:    string(msg.Role),
-					Content: text,
+					Content: text.String(),
 				}
 			}
 

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"
@@ -321,24 +323,68 @@ func (m *Kit) GetSessionMessages() []extensions.SessionMessage {
 			continue
 		}
 		// Flatten content parts into a single text string.
-		var content string
+		var content strings.Builder
 		for _, p := range msg.Parts {
 			switch pt := p.(type) {
 			case message.TextContent:
-				content += pt.Text
+				content.WriteString(pt.Text)
 			case message.ReasoningContent:
-				content += pt.Thinking
+				content.WriteString(pt.Thinking)
 			case message.ToolCall:
-				content += fmt.Sprintf("[tool_call: %s(%s)]", pt.Name, pt.Input)
+				fmt.Fprintf(&content, "[tool_call: %s(%s)]", pt.Name, pt.Input)
 			case message.ToolResult:
-				content += fmt.Sprintf("[tool_result: %s]", pt.Content)
+				fmt.Fprintf(&content, "[tool_result: %s]", pt.Content)
 			}
 		}
 		msgs = append(msgs, extensions.SessionMessage{
 			ID:        me.ID,
 			ParentID:  me.ParentID,
 			Role:      string(msg.Role),
-			Content:   content,
+			Content:   content.String(),
+			Model:     msg.Model,
+			Provider:  msg.Provider,
+			Timestamp: me.Timestamp.Format("2006-01-02T15:04:05Z07:00"),
+		})
+	}
+	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"),
@@ -485,6 +531,7 @@ func (m *Kit) SetModel(ctx context.Context, modelString string) error {
 		ProviderURL:    viper.GetString("provider-url"),
 		MaxTokens:      viper.GetInt("max-tokens"),
 		TLSSkipVerify:  viper.GetBool("tls-skip-verify"),
+		ThinkingLevel:  models.ParseThinkingLevel(viper.GetString("thinking-level")),
 	}
 	temperature := float32(viper.GetFloat64("temperature"))
 	config.Temperature = &temperature
@@ -618,9 +665,10 @@ func (m *Kit) ReloadExtensions() error {
 // used, and closed.
 func (m *Kit) ExecuteCompletion(ctx context.Context, req extensions.CompleteRequest) (extensions.CompleteResponse, error) {
 	var (
-		llmModel  fantasy.LanguageModel
-		closer    func()
-		usedModel string
+		llmModel    fantasy.LanguageModel
+		closer      func()
+		usedModel   string
+		providerOps fantasy.ProviderOptions
 	)
 
 	if req.Model == "" {
@@ -643,6 +691,7 @@ func (m *Kit) ExecuteCompletion(ctx context.Context, req extensions.CompleteRequ
 		}
 		llmModel = providerResult.Model
 		usedModel = req.Model
+		providerOps = providerResult.ProviderOptions
 		closer = func() {
 			if providerResult.Closer != nil {
 				_ = providerResult.Closer.Close()
@@ -659,6 +708,9 @@ func (m *Kit) ExecuteCompletion(ctx context.Context, req extensions.CompleteRequ
 	if req.MaxTokens > 0 {
 		agentOpts = append(agentOpts, fantasy.WithMaxOutputTokens(int64(req.MaxTokens)))
 	}
+	if providerOps != nil {
+		agentOpts = append(agentOpts, fantasy.WithProviderOptions(providerOps))
+	}
 
 	completionAgent := fantasy.NewAgent(llmModel, agentOpts...)
 
@@ -843,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()
@@ -1144,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.
@@ -1159,6 +1227,143 @@ 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()
+
+	// Fall back to parent's model.
+	model := cfg.Model
+	if model == "" {
+		model = m.modelString
+	}
+
+	// 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.
+	child, err := New(ctx, &Options{
+		Model:        model,
+		SystemPrompt: systemPrompt,
+		Tools:        tools,
+		NoSession:    cfg.NoSession,
+		Quiet:        true,
+	})
+	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
 // ---------------------------------------------------------------------------
@@ -1167,22 +1372,61 @@ type TurnResult struct {
 // All prompt modes (Prompt, Steer, FollowUp, PromptWithOptions) share this
 // single code path so callback wiring is never duplicated.
 func (m *Kit) generate(ctx context.Context, messages []fantasy.Message) (*agent.GenerateWithLoopResult, error) {
+	// Inject the in-process subagent spawner into the context so the
+	// spawn_subagent core tool can create child Kit instances without
+	// importing pkg/kit (which would create an import cycle).
+	ctx = core.WithSubagentSpawner(ctx, func(
+		spawnCtx context.Context, prompt, model, systemPrompt string, timeout time.Duration,
+	) (*core.SubagentSpawnResult, error) {
+		result, err := m.Subagent(spawnCtx, SubagentConfig{
+			Prompt:       prompt,
+			Model:        model,
+			SystemPrompt: systemPrompt,
+			Timeout:      timeout,
+		})
+		if result == nil {
+			return &core.SubagentSpawnResult{Error: err}, err
+		}
+		sr := &core.SubagentSpawnResult{
+			Response:  result.Response,
+			Error:     result.Error,
+			SessionID: result.SessionID,
+			Elapsed:   result.Elapsed,
+		}
+		if result.Usage != nil {
+			sr.InputTokens = result.Usage.InputTokens
+			sr.OutputTokens = result.Usage.OutputTokens
+		}
+		return sr, err
+	})
+
 	return m.agent.GenerateWithLoopAndStreaming(ctx, messages,
-		func(toolName, toolArgs string) {
-			m.events.emit(ToolCallEvent{ToolName: toolName, ToolArgs: toolArgs})
+		func(toolCallID, toolName, toolArgs string) {
+			m.events.emit(ToolCallEvent{
+				ToolCallID: toolCallID, ToolName: toolName, ToolKind: toolKindFor(toolName),
+				ToolArgs: toolArgs, ParsedArgs: parseToolArgs(toolArgs),
+			})
 		},
-		func(toolName string, isStarting bool) {
+		func(toolCallID, toolName, toolArgs string, isStarting bool) {
 			if isStarting {
-				m.events.emit(ToolExecutionStartEvent{ToolName: toolName})
+				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})
@@ -1193,6 +1437,9 @@ func (m *Kit) generate(ctx context.Context, messages []fantasy.Message) (*agent.
 		func(chunk string) {
 			m.events.emit(MessageUpdateEvent{Chunk: chunk})
 		},
+		func(delta string) {
+			m.events.emit(ReasoningDeltaEvent{Delta: delta})
+		},
 	)
 }
 
@@ -1213,10 +1460,12 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr
 	// <skill> block, and appends any trailing user args.
 	if expanded := m.expandSkillCommand(prompt); expanded != prompt {
 		prompt = expanded
-		// Replace the last user message in preMessages with the expanded text.
+		// Replace the last user message in preMessages with the expanded text,
+		// preserving any file parts (e.g. clipboard images).
 		for i := len(preMessages) - 1; i >= 0; i-- {
 			if preMessages[i].Role == fantasy.MessageRoleUser {
-				preMessages[i] = fantasy.NewUserMessage(expanded)
+				files := extractFileParts(preMessages[i])
+				preMessages[i] = fantasy.NewUserMessage(expanded, files...)
 				break
 			}
 		}
@@ -1225,11 +1474,13 @@ func (m *Kit) runTurn(ctx context.Context, promptLabel string, prompt string, pr
 	// Run BeforeTurn hooks — can modify the prompt, inject system/context messages.
 	if m.beforeTurn.hasHooks() {
 		if hookResult := m.beforeTurn.run(BeforeTurnHook{Prompt: prompt}); hookResult != nil {
-			// Override prompt text in the last user message.
+			// Override prompt text in the last user message, preserving
+			// any file parts (e.g. clipboard images).
 			if hookResult.Prompt != nil {
 				for i := len(preMessages) - 1; i >= 0; i-- {
 					if preMessages[i].Role == fantasy.MessageRoleUser {
-						preMessages[i] = fantasy.NewUserMessage(*hookResult.Prompt)
+						files := extractFileParts(preMessages[i])
+						preMessages[i] = fantasy.NewUserMessage(*hookResult.Prompt, files...)
 						break
 					}
 				}
@@ -1304,8 +1555,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() {
@@ -1314,8 +1567,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
@@ -1460,6 +1715,15 @@ func (m *Kit) PromptResult(ctx context.Context, message string) (*TurnResult, er
 	})
 }
 
+// PromptResultWithFiles sends a multimodal message (text + images) and returns
+// the full turn result. The files parameter carries binary file data (e.g.
+// clipboard images) that are included alongside the text in the user message.
+func (m *Kit) PromptResultWithFiles(ctx context.Context, message string, files []fantasy.FilePart) (*TurnResult, error) {
+	return m.runTurn(ctx, message, message, []fantasy.Message{
+		fantasy.NewUserMessage(message, files...),
+	})
+}
+
 // ClearSession resets the tree session's leaf pointer to the root, starting
 // a fresh conversation branch.
 func (m *Kit) ClearSession() {
@@ -1483,11 +1747,44 @@ func (m *Kit) GetModelInfo() *ModelInfo {
 	return LookupModel(provider, modelID)
 }
 
+// IsReasoningModel returns true if the current model supports extended thinking / reasoning.
+func (m *Kit) IsReasoningModel() bool {
+	info := m.GetModelInfo()
+	return info != nil && info.Reasoning
+}
+
+// GetThinkingLevel returns the current thinking level.
+func (m *Kit) GetThinkingLevel() string {
+	return viper.GetString("thinking-level")
+}
+
+// SetThinkingLevel changes the thinking level and recreates the agent with
+// the new thinking budget. Returns an error if provider recreation fails.
+func (m *Kit) SetThinkingLevel(ctx context.Context, level string) error {
+	viper.Set("thinking-level", level)
+	// Recreate agent with new thinking config by re-running SetModel
+	// with the same model string. SetModel rebuilds the provider and
+	// passes the updated viper config (including thinking-level).
+	return m.SetModel(ctx, m.modelString)
+}
+
 // GetTools returns all tools available to the agent (core + MCP + extensions).
 func (m *Kit) GetTools() []Tool {
 	return m.agent.GetTools()
 }
 
+// extractFileParts returns all FilePart entries from a message's Content.
+// Used to preserve image attachments when replacing user message text.
+func extractFileParts(msg fantasy.Message) []fantasy.FilePart {
+	var files []fantasy.FilePart
+	for _, part := range msg.Content {
+		if fp, ok := part.(fantasy.FilePart); ok {
+			files = append(files, fp)
+		}
+	}
+	return files
+}
+
 // Close cleans up resources including MCP server connections, model resources,
 // and the tree session file handle. Should be called when the Kit instance is
 // no longer needed. Returns an error if cleanup fails.

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

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