feat(sdk): support mcp-go in-process transport for MCP servers

- Add InProcessServer field to MCPServerConfig (json:"-", never serialized)
- Add "inprocess" transport type to config, validation, and connection pool
- Add createInProcessClient() using mcp-go client.NewInProcessClient()
- Add Kit.AddInProcessMCPServer() convenience method
- Add Options.InProcessMCPServers for init-time registration
- Export MCPServer type alias (= server.MCPServer) in pkg/kit/types.go
- Add 8 tests covering config, pool, tool manager, and edge cases
- Update SDK README, kit-sdk skill, and www docs

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,79 @@
+name: Bug Report
+description: Report a bug or issue with Kit
+title: "fix: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: What happened? What did you expect to happen?
+      placeholder: |
+        The BorderColor field in ToolRenderConfig is documented but never applied 
+        during tool rendering. I expected the tool block to render with my custom 
+        color, but it uses the default styling instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Provide clear steps to reproduce the issue
+      placeholder: |
+        1. Create an extension with `api.RegisterToolRenderer(ext.ToolRenderConfig{...})`
+        2. Set `BorderColor: "#89b4fa"` in the config
+        3. Run a tool that uses this renderer
+        4. Observe the border color is not applied
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Relevant Code / Configuration
+      description: Paste any code, configuration, or error messages
+      placeholder: |
+        ```go
+        api.RegisterToolRenderer(ext.ToolRenderConfig{
+            ToolName:    "bash",
+            DisplayName: "Shell",
+            BorderColor: "#a6e3a1",  // This is ignored!
+            Background:  "#1e1e2e",  // This is ignored!
+        })
+        ```
+      render: go
+
+  - type: input
+    id: component
+    attributes:
+      label: Affected Component
+      description: Which part of Kit is affected?
+      placeholder: e.g., extensions, ui, tool rendering, session management
+
+  - type: input
+    id: version
+    attributes:
+      label: Kit Version
+      description: What version of Kit are you running?
+      placeholder: e.g., v0.1.0, commit hash, or "main"
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, proposed fixes, or related issues
+      placeholder: |
+        The issue appears to be in `internal/ui/messages.go:RenderToolMessage()` 
+        which ignores the BorderColor and Background fields from ToolRendererData.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I've searched existing issues and this hasn't been reported yet
+          required: true
+        - label: I've tested with the latest version of Kit
+          required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Kit Documentation
+    url: https://github.com/mark3labs/kit/tree/main/www/pages
+    about: Check the documentation before filing an issue
+  - name: Extension Examples
+    url: https://github.com/mark3labs/kit/tree/main/examples/extensions
+    about: See working extension examples for reference
+  - name: Discussions
+    url: https://github.com/mark3labs/kit/discussions
+    about: For questions, ideas, or general discussion

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,40 @@
+name: Documentation Issue
+description: Report missing, incorrect, or unclear documentation
+title: "docs: "
+labels: ["documentation"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Documentation Issue
+      description: What's wrong or missing in the documentation?
+      placeholder: |
+        The ToolRenderConfig documentation mentions BorderColor and Background fields,
+        but the code doesn't actually use them. The docs should either be updated 
+        to reflect reality, or the bug should be fixed.
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Documentation Location
+      description: Where is the affected documentation?
+      placeholder: e.g., README.md, examples/extensions/tool-renderer-demo.go, pkg/kit docs
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested Improvement
+      description: How should the documentation be improved?
+      placeholder: |
+        Add a note that BorderColor and Background are not yet implemented, 
+        or fix the bug and document the correct behavior.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I've checked that this documentation issue still exists in the latest version
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,64 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for Kit
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature Description
+      description: What would you like to see added or changed?
+      placeholder: |
+        I'd like to be able to customize the border color of tool result blocks 
+        dynamically based on the tool type or result status.
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation / Use Case
+      description: Why is this feature needed? What problem does it solve?
+      placeholder: |
+        When running multiple tools in sequence, it's hard to visually distinguish 
+        between file reads (blue), shell commands (green), and errors (red) 
+        without custom border colors.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed
+    attributes:
+      label: Proposed Implementation
+      description: How do you think this should work? (optional)
+      placeholder: |
+        Extend `ToolRenderConfig` to accept a function that receives the tool 
+        result and returns a color based on the content:
+        
+        ```go
+        BorderColorFunc: func(result string, isError bool) string {
+            if isError {
+                return "#f38ba8"
+            }
+            return "#89b4fa"
+        }
+        ```
+      render: go
+
+  - type: checkboxes
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      options:
+        - label: I've considered workarounds or alternative approaches
+          required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I've searched existing issues and this hasn't been requested yet
+          required: true
+        - label: This feature aligns with Kit's design philosophy (TUI-first, extension-based)
+          required: false

.kit/extensions/go-edit-lint.go

@@ -28,11 +28,15 @@ type lintResult struct {
 	Err    error
 }
 
+// Package-level state: set of .go files edited during the current agent turn.
+var editedFiles map[string]bool
+
 func Init(api ext.API) {
 	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
-		ctx.Print("go-edit-lint extension loaded - will run gopls and golangci-lint on Go file edits")
+		ctx.Print("go-edit-lint extension loaded - will run gopls and golangci-lint after agent turns that edit Go files")
 	})
 
+	// Track edited .go files — don't lint yet.
 	api.OnToolResult(func(e ext.ToolResultEvent, ctx ext.Context) *ext.ToolResultResult {
 		if e.IsError || !isEditOrWrite(e.ToolName) {
 			return nil
@@ -43,30 +47,72 @@ func Init(api ext.API) {
 			return nil
 		}
 
-		report := runGoDiagnostics(ctx.CWD, absPath)
-		
-		// Check if there are issues and add explicit prompt for the LLM to react
-		goplsIssues, lintIssues := countIssues(report)
-		hasIssues := goplsIssues > 0 || lintIssues > 0
-		
-		var enhanced string
-		if hasIssues {
-			enhanced = e.Content + "\n\n" + report + "\n\n⚠️ DIAGNOSTICS FOUND: Please review the issues above and fix them before proceeding."
-		} else {
-			enhanced = e.Content + "\n\n" + report
+		if editedFiles == nil {
+			editedFiles = make(map[string]bool)
+		}
+		editedFiles[absPath] = true
+		return nil
+	})
+
+	// After the agent turn ends, lint all collected files.
+	api.OnAgentEnd(func(e ext.AgentEndEvent, ctx ext.Context) {
+		if len(editedFiles) == 0 {
+			return
 		}
 
-		// Show TUI message block for diagnostics visibility (only if there are issues)
+		// Snapshot and reset immediately so the next turn starts clean.
+		files := editedFiles
+		editedFiles = nil
+
+		// Skip lint on errored turns.
+		if e.StopReason == "error" {
+			return
+		}
+
+		// Collect unique directories and file list for gopls.
+		var allGoplsOutput []string
+		for absPath := range files {
+			res := runGopls(ctx.CWD, absPath)
+			formatted := formatToolResult(res, "")
+			if formatted != "" {
+				allGoplsOutput = append(allGoplsOutput, fmt.Sprintf("# %s\n%s", filepath.Base(absPath), formatted))
+			}
+		}
+
+		lintRes := runGolangCILint(ctx.CWD, "./...")
+
+		goplsSection := "No diagnostics."
+		if len(allGoplsOutput) > 0 {
+			goplsSection = strings.Join(allGoplsOutput, "\n\n")
+		}
+		lintSection := formatToolResult(lintRes, "No lint issues.")
+
+		// Build file list for the report header.
+		var fileNames []string
+		for absPath := range files {
+			fileNames = append(fileNames, filepath.Base(absPath))
+		}
+
+		report := fmt.Sprintf(
+			"<go_diagnostics files=%q>\n[gopls]\n%s\n\n[golangci-lint]\n%s\n</go_diagnostics>",
+			strings.Join(fileNames, ", "),
+			goplsSection,
+			lintSection,
+		)
+
+		goplsIssues, lintIssues := countIssues(report)
+		hasIssues := goplsIssues > 0 || lintIssues > 0
+
 		if hasIssues {
+			// Show TUI block so the user sees it too.
 			var msgLines []string
-			msgLines = append(msgLines, fmt.Sprintf("File: %s", filepath.Base(absPath)))
+			msgLines = append(msgLines, fmt.Sprintf("Files: %s", strings.Join(fileNames, ", ")))
 			if goplsIssues > 0 {
 				msgLines = append(msgLines, fmt.Sprintf("gopls: %d issue(s)", goplsIssues))
 			}
 			if lintIssues > 0 {
 				msgLines = append(msgLines, fmt.Sprintf("golangci-lint: %d issue(s)", lintIssues))
 			}
-			msgLines = append(msgLines, "", "⚠️ Please fix these issues before proceeding.")
 
 			borderColor := "#f9e2af" // yellow
 			if goplsIssues > 0 && lintIssues > 0 {
@@ -78,9 +124,16 @@ func Init(api ext.API) {
 				BorderColor: borderColor,
 				Subtitle:    "go-edit-lint",
 			})
-		}
 
-		return &ext.ToolResultResult{Content: &enhanced}
+			// Inject a follow-up message so the agent fixes the issues.
+			ctx.SendMessage(report + "\n\n⚠️ DIAGNOSTICS FOUND: Please review and fix the issues above.")
+		} else {
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        fmt.Sprintf("Files: %s\n✓ All clean", strings.Join(fileNames, ", ")),
+				BorderColor: "#a6e3a1",
+				Subtitle:    "go-edit-lint",
+			})
+		}
 	})
 }
 
@@ -106,18 +159,6 @@ func resolveGoFilePath(inputJSON, cwd string) (string, bool) {
 	return absPath, true
 }
 
-func runGoDiagnostics(cwd, absPath string) string {
-	gopls := runGopls(cwd, absPath)
-	lint := runGolangCILint(cwd, "./...")
-
-	return fmt.Sprintf(
-		"<go_diagnostics file=%q>\n[gopls]\n%s\n\n[golangci-lint]\n%s\n</go_diagnostics>",
-		filepath.Base(absPath),
-		formatToolResult(gopls, "No diagnostics."),
-		formatToolResult(lint, "No lint issues."),
-	)
-}
-
 func runGopls(cwd, absPath string) lintResult {
 	ctx, cancel := context.WithTimeout(context.Background(), diagnosticsTimeout)
 	defer cancel()
@@ -178,7 +219,9 @@ func formatToolResult(res lintResult, emptyFallback string) string {
 	out := strings.TrimSpace(res.Output)
 	if out == "" {
 		if res.Err == nil {
-			lines = append(lines, emptyFallback)
+			if emptyFallback != "" {
+				lines = append(lines, emptyFallback)
+			}
 		}
 	} else {
 		lines = append(lines, out)
@@ -197,17 +240,15 @@ func truncate(s string, max int) string {
 }
 
 func countIssues(report string) (goplsCount, lintCount int) {
-	// Extract gopls section
 	goplsStart := strings.Index(report, "[gopls]")
 	lintStart := strings.Index(report, "[golangci-lint]")
 	endTag := strings.Index(report, "</go_diagnostics>")
 
 	if goplsStart != -1 && lintStart != -1 {
 		goplsSection := report[goplsStart:lintStart]
-		// Count non-empty lines excluding the header and "No diagnostics." message
 		for _, line := range strings.Split(goplsSection, "\n") {
 			line = strings.TrimSpace(line)
-			if line != "" && line != "[gopls]" && line != "No diagnostics." {
+			if line != "" && line != "[gopls]" && line != "No diagnostics." && !strings.HasPrefix(line, "#") {
 				goplsCount++
 			}
 		}
@@ -215,7 +256,6 @@ func countIssues(report string) (goplsCount, lintCount int) {
 
 	if lintStart != -1 && endTag != -1 {
 		lintSection := report[lintStart:endTag]
-		// Count non-empty lines excluding the header and "No lint issues." message
 		for _, line := range strings.Split(lintSection, "\n") {
 			line = strings.TrimSpace(line)
 			if line != "" && line != "[golangci-lint]" && line != "No lint issues." {

.kit/prompts/feature-request.md

@@ -0,0 +1,86 @@
+---
+description: Create a feature request using the GitHub template
+---
+
+Create a feature request for the Kit repository. The user wants to request: $+
+
+## Feature Request Template
+
+This prompt uses the `feature_request` GitHub template which requires:
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| **Feature Description** | Yes | What should be added or changed |
+| **Motivation / Use Case** | Yes | Why is this needed? What problem does it solve? |
+| **Proposed Implementation** | No | How do you think this should work? |
+
+## Steps
+
+1. **Understand the request** from `$+`
+   - What capability is missing?
+   - What would the ideal behavior look like?
+
+2. **Ask clarifying questions** if needed:
+   - "What problem does this solve for you?"
+   - "How would you expect this to work?"
+   - "Are there similar features in other tools you use?"
+
+3. **Craft the title** using conventional format:
+   - `feat: <short description>`
+   - Lowercase, imperative mood, ≤72 chars
+   - Good examples:
+     - `feat: add keyboard shortcut for clearing input`
+     - `feat: support custom themes per extension`
+     - `feat: add fuzzy matching to model selector`
+   - Bad examples:
+     - `Feature request: can we have...` (too vague)
+     - `It would be nice if...` (not imperative)
+
+4. **Build the body** with the template fields:
+
+   **Feature Description:**
+   - Clear statement of what to add/change
+   - Be specific about the behavior
+   - Include UI/UX details if relevant
+
+   **Motivation / Use Case:**
+   - What problem does this solve?
+   - Current workaround (if any) and why it's insufficient
+   - Who benefits from this feature?
+
+   **Proposed Implementation** (optional but helpful):
+   - High-level approach
+   - API changes if applicable
+   - Example usage code
+
+5. **Create the issue**:
+   ```bash
+   gh issue create --template feature_request --title "feat: ..." --body "..."
+   ```
+
+6. **Confirm success**:
+   - Show the issue URL and number
+   - Mention it was created with the feature_request template
+
+## Guidelines
+
+- Focus on the *problem* first, then the solution
+- Include concrete examples of how the feature would be used
+- Consider edge cases and mention them
+- If proposing API changes, show before/after code
+- Check if similar features exist in related tools (mention them for reference)
+- Align with Kit's philosophy: TUI-first, extension-based, keyboard-driven
+
+## Example
+
+User: `/feature-request I want to be able to customize tool border colors dynamically`
+
+You:
+1. Title: `feat: dynamic border colors for tool results based on status`
+2. Body:
+   - **Feature Description**: Allow `ToolRenderConfig` to accept a function that determines border color based on tool result content or status, enabling dynamic visual feedback.
+   - **Motivation**: When running multiple tools, it's hard to distinguish file reads (blue), shell commands (green), and errors (red) without custom colors per result.
+   - **Proposed Implementation**: Add `BorderColorFunc` callback that receives `(result string, isError bool)` and returns a color string.
+
+3. Execute: `gh issue create --template feature_request --title "feat: ..." --body "..."`
+4. Confirm: Created issue #43 using feature_request template

.kit/prompts/file-issue.md

@@ -0,0 +1,100 @@
+---
+description: File a GitHub issue using the appropriate template
+---
+
+File a GitHub issue for the Kit repository. The user wants to create an issue about: $+
+
+## Issue Templates Available
+
+This repository has structured issue templates. You MUST use the appropriate template:
+
+| Type | Template | Use For |
+|------|----------|---------|
+| `bug` | `bug_report` | Something is broken, not working as expected |
+| `feat` | `feature_request` | New feature, enhancement, improvement |
+| `docs` | `documentation` | Missing, incorrect, or unclear documentation |
+
+## Steps
+
+1. **Determine the issue type** from `$+`:
+   - Bug → use `--template bug_report`
+   - Feature → use `--template feature_request`  
+   - Documentation → use `--template documentation`
+
+2. **Ask clarifying questions** if critical info is missing:
+   - For bugs: "What were you doing when this happened?" (reproduction steps)
+   - For features: "What problem does this solve?" (motivation)
+   - For docs: "Where did you look for this information?" (location)
+
+3. **Craft the title** using conventional format:
+   - `<type>: <short description>`
+   - Lowercase, imperative mood, ≤72 chars
+   - Examples:
+     - `fix: ToolRenderConfig BorderColor ignored during rendering`
+     - `feat: add keyboard shortcut for clearing input`
+     - `docs: clarify extension widget lifecycle`
+
+4. **File the issue** using the template:
+   ```bash
+   # For bugs
+   gh issue create --template bug_report --title "fix: ..." --body "..."
+   
+   # For features
+   gh issue create --template feature_request --title "feat: ..." --body "..."
+   
+   # For documentation
+   gh issue create --template documentation --title "docs: ..." --body "..."
+   ```
+
+   The template will guide the user through the required fields. You need to provide:
+   - **Bug reports**: Description, reproduction steps, expected vs actual behavior
+   - **Feature requests**: Description, motivation/use case, optional proposed implementation
+   - **Documentation**: Description, location of docs, suggested improvement
+
+5. **Confirm success** by showing:
+   - The issue URL
+   - The issue number
+   - Which template was used
+
+## Template Field Guide
+
+### Bug Report (`bug_report`)
+Required fields in the body:
+- **Bug Description** - what happened vs expected
+- **Steps to Reproduce** - numbered list to recreate the bug
+- **Relevant Code** - code snippets, configuration, error messages
+- **Component** - which part of Kit (ui, extensions, session, etc.)
+- **Version** - Kit version or commit hash
+
+### Feature Request (`feature_request`)
+Required fields in the body:
+- **Feature Description** - what to add/change
+- **Motivation / Use Case** - why this is needed
+- **Proposed Implementation** - how it could work (optional)
+
+### Documentation (`documentation`)
+Required fields in the body:
+- **Documentation Issue** - what's wrong or missing
+- **Documentation Location** - file or URL where docs exist
+- **Suggested Improvement** - how to fix the docs
+
+## Guidelines
+
+- ALWAYS use `--template <name>` instead of bare `gh issue create`
+- Include file paths and line numbers when you know them
+- Use triple backticks for code blocks
+- Keep the body factual - avoid speculation unless in "Proposed Fix" section
+- If you're unsure about technical details, say so in the issue
+- For UI bugs, describe what you see vs what you expect
+- For API bugs, include the relevant struct/function names
+
+## Example Usage
+
+User: `/file-issue The ToolRenderConfig BorderColor field is documented but never used in rendering`
+
+You: 
+1. Determine this is a **bug** (documented field doesn't work)
+2. Use `--template bug_report`
+3. Gather: reproduction steps (register renderer with BorderColor), expected (custom color), actual (default color)
+4. Create issue with title `fix: ToolRenderConfig BorderColor and Background fields are ignored`
+5. Confirm: Created issue #42 using bug_report template

.kit/prompts/new-prompt.md

@@ -2,7 +2,7 @@
 description: Scaffold a new prompt template in .kit/prompts/
 ---
 
-Create a new kit prompt template. The user wants a prompt that does: $@
+Create a new kit prompt template. The user wants a prompt that does: $+
 
 ## What a prompt template is
 
@@ -23,19 +23,21 @@ $1 $2 etc. for positional arguments.
 - **Filename** → slug: `commit-push.md` becomes `/commit-push`
 - **Frontmatter**: only `description` is recognised; keep it under ~80 chars
 - **Body**: plain markdown; the full text is submitted as the user's message when the template fires
-- **Arguments**: `$@` expands to everything the user typed after the slash command name;
+- **Arguments**: `$+` expands to everything the user typed after the slash command name
+  (requires at least one argument); `$@` is the same but allows zero arguments;
   `$1`, `$2` for individual positional args; omit entirely if no arguments are needed
 
 ## Steps
 
-1. **Understand the workflow** the user described in `$@` — ask a clarifying question if the intent is ambiguous
+1. **Understand the workflow** the user described in `$+` — ask a clarifying question if the intent is ambiguous
 2. **Choose a filename**: short, lowercase, hyphen-separated, descriptive (e.g. `code-review.md`)
 3. **Write the description**: one sentence, imperative, fits in autocomplete
 4. **Draft the body**:
    - Open with a single sentence stating the goal
    - Use `## Steps` for multi-step workflows; use plain prose for simple prompts
    - Be specific: name commands, flags, and file paths where relevant
-   - End with `$@` on its own line if the user might want to pass context or a hint; omit if the prompt is self-contained
+   - End with `$+` on its own line if the user must pass context; use `$@` if arguments
+     are optional; omit if the prompt is self-contained
 5. **Write the file** to `.kit/prompts/<slug>.md`
 6. **Confirm** by showing the final file content and the slash command that activates it
 

README.md

@@ -19,6 +19,7 @@ A powerful, extensible AI coding agent CLI with multi-provider support, built-in
 
 - **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, subagent - no MCP overhead
+- **Smart @ Attachments**: Binary files auto-detected via MIME type, MCP resources via `@mcp:server:uri`
 - **MCP Integration**: Connect external MCP servers for expanded capabilities
 - **Extension System**: Write custom tools, commands, widgets, and UI modifications in Go
 - **Theming**: 22 built-in color themes (KITT, Catppuccin, Dracula, Nord, etc.) with runtime switching, persistence, and custom theme files
@@ -191,6 +192,8 @@ mcpServers:
 --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)
+--frequency-penalty      Penalize frequent tokens 0.0-2.0 (default: 0.0)
+--presence-penalty       Penalize present tokens 0.0-2.0 (default: 0.0)
 --thinking-level         Extended thinking level: off, minimal, low, medium, high (default: off)
 
 # System
@@ -317,39 +320,40 @@ kit -e examples/extensions/minimal.go
 
 See the `examples/extensions/` directory:
 
-- `minimal.go` - Clean UI with custom footer
-- `auto-commit.go` - Auto-commit on shutdown
-- `bookmark.go` - Bookmark conversations
-- `branded-output.go` - Branded output rendering
-- `compact-notify.go` - Notification on compaction
-- `confirm-destructive.go` - Confirm destructive operations
-- `context-inject.go` - Inject context into conversations
-- `conversation-manager.go` - **NEW** Tree navigation, branch summarization, and fresh context loops
-- `custom-editor-demo.go` - Vim-like modal editor
-- `dev-reload.go` - Development live-reload
-- `header-footer-demo.go` - Custom headers and footers
-- `inline-bash.go` - Inline bash execution
-- `interactive-shell.go` - Interactive shell integration
-- `kit-kit.go` - Kit-in-Kit (sub-agent spawning)
-- `lsp-diagnostics.go` - LSP diagnostic integration
-- `notify.go` - Desktop notifications
-- `overlay-demo.go` - Modal dialogs
-- `permission-gate.go` - Permission gating for tools
-- `pirate.go` - Pirate-themed personality
-- `plan-mode.go` - Read-only planning mode
-- `project-rules.go` - Project-specific rules
-- `prompt-demo.go` - Interactive prompts (select/confirm/input)
-- `prompt-templates.go` - **NEW** Frontmatter-driven templates with model switching and skill injection
-- `protected-paths.go` - Path protection for sensitive files
-- `subagent-widget.go` - Multi-agent orchestration with status widget
-- `subagent-test.go` - Subagent testing utilities
-- `summarize.go` - Conversation summarization
-- `tool-logger.go` - Log all tool calls
-- `neon-theme.go` - Custom theme registration and switching
-- `tool-renderer-demo.go` - Custom tool call rendering
-- `widget-status.go` - Persistent status widgets
+- [`minimal.go`](examples/extensions/minimal.go) - Clean UI with custom footer
+- [`auto-commit.go`](examples/extensions/auto-commit.go) - Auto-commit on shutdown
+- [`bookmark.go`](examples/extensions/bookmark.go) - Bookmark conversations
+- [`branded-output.go`](examples/extensions/branded-output.go) - Branded output rendering
+- [`bridge-demo.go`](examples/extensions/bridge_demo.go) - Bridged SDK API demo (tree navigation, skills, templates, model resolution)
+- [`compact-notify.go`](examples/extensions/compact-notify.go) - Notification on compaction
+- [`confirm-destructive.go`](examples/extensions/confirm-destructive.go) - Confirm destructive operations
+- [`context-inject.go`](examples/extensions/context-inject.go) - Inject context into conversations
+- [`conversation-manager.go`](examples/extensions/conversation-manager.go) - **NEW** Tree navigation, branch summarization, and fresh context loops
+- [`custom-editor-demo.go`](examples/extensions/custom-editor-demo.go) - Vim-like modal editor
+- [`dev-reload.go`](examples/extensions/dev-reload.go) - Development live-reload
+- [`header-footer-demo.go`](examples/extensions/header-footer-demo.go) - Custom headers and footers
+- [`inline-bash.go`](examples/extensions/inline-bash.go) - Inline bash execution
+- [`interactive-shell.go`](examples/extensions/interactive-shell.go) - Interactive shell integration
+- [`kit-kit.go`](examples/extensions/kit-kit.go) - Kit-in-Kit (sub-agent spawning)
+- [`lsp-diagnostics.go`](examples/extensions/lsp-diagnostics.go) - LSP diagnostic integration
+- [`notify.go`](examples/extensions/notify.go) - Desktop notifications
+- [`overlay-demo.go`](examples/extensions/overlay-demo.go) - Modal dialogs
+- [`permission-gate.go`](examples/extensions/permission-gate.go) - Permission gating for tools
+- [`pirate.go`](examples/extensions/pirate.go) - Pirate-themed personality
+- [`plan-mode.go`](examples/extensions/plan-mode.go) - Read-only planning mode
+- [`project-rules.go`](examples/extensions/project-rules.go) - Project-specific rules
+- [`prompt-demo.go`](examples/extensions/prompt-demo.go) - Interactive prompts (select/confirm/input)
+- [`prompt-templates.go`](examples/extensions/prompt-templates.go) - **NEW** Frontmatter-driven templates with model switching and skill injection
+- [`protected-paths.go`](examples/extensions/protected-paths.go) - Path protection for sensitive files
+- [`subagent-widget.go`](examples/extensions/subagent-widget.go) - Multi-agent orchestration with status widget
+- [`subagent-test.go`](examples/extensions/subagent-test.go) - Subagent testing utilities
+- [`summarize.go`](examples/extensions/summarize.go) - Conversation summarization
+- [`tool-logger.go`](examples/extensions/tool-logger.go) - Log all tool calls
+- [`neon-theme.go`](examples/extensions/neon-theme.go) - Custom theme registration and switching
+- [`tool-renderer-demo.go`](examples/extensions/tool-renderer-demo.go) - Custom tool call rendering
+- [`widget-status.go`](examples/extensions/widget-status.go) - Persistent status widgets
 
-Also see `.kit/extensions/go-edit-lint.go` (in this repo) for a project-local extension example that runs gopls and golangci-lint on Go file edits.
+Also see [`.kit/extensions/go-edit-lint.go`](.kit/extensions/go-edit-lint.go) (in this repo) for a project-local extension example that runs gopls and golangci-lint on Go file edits.
 
 ### Loading Extensions
 
@@ -406,7 +410,7 @@ func TestMyExtension(t *testing.T) {
 - `AssertPrinted()`, `AssertPrintedContains()` — Verify output
 - `AssertToolRegistered()`, `AssertCommandRegistered()` — Verify registration
 
-See `examples/extensions/tool-logger_test.go` for a complete example with 14 test cases covering tool calls, input handling, and session lifecycle.
+See [`examples/extensions/tool-logger_test.go`](examples/extensions/tool-logger_test.go) for a complete example with 14 test cases covering tool calls, input handling, and session lifecycle.
 
 ### Prompt Templates
 
@@ -428,10 +432,13 @@ Focus on $1 specifically.
 
 **Argument placeholders:**
 - `$1`, `$2`, etc. — Individual arguments
-- `$@` or `$ARGUMENTS` — All arguments
+- `$@` or `$ARGUMENTS` — All arguments (zero or more)
+- `$+` — All arguments (one or more required; error if none given)
 - `${@:2}` — Arguments from position 2 onwards
 - `${@:1:3}` — 3 arguments starting at position 1
 
+Placeholders inside fenced code blocks (```) and inline code spans are ignored.
+
 Disable templates with `--no-prompt-templates` or load a specific template with `--prompt-template <name>`.
 
 ## Session Management
@@ -477,9 +484,18 @@ During an interactive session, use these slash commands:
 | `/import <path>` | Import and switch to a session from a JSONL file |
 | `/share` | Upload session to GitHub Gist and get a shareable viewer URL |
 | `/tree` | Navigate the session tree |
-| `/fork` | Branch from an earlier message |
+| `/fork` | Fork to new session from an earlier message |
 | `/new` | Start a fresh session |
 
+### Keyboard Shortcuts
+
+| Shortcut | Description |
+|----------|-------------|
+| `Ctrl+X e` | Open `$VISUAL`/`$EDITOR` to compose or edit your prompt |
+| `Ctrl+X s` | Steer — inject a system-level instruction mid-turn |
+| `ESC ESC` | Cancel the current operation (tool call or streaming) |
+| `↑` / `↓` | Navigate prompt history |
+
 ## Go SDK
 
 Embed Kit in your Go applications:
@@ -531,7 +547,12 @@ host, err := kit.New(ctx, &kit.Options{
     NoSession:    true,                // Ephemeral mode
 
     // Tool options
-    ExtraTools:   []kit.Tool{...},     // Additional tools alongside defaults
+    Tools:            []kit.Tool{...},     // Replace default tool set entirely
+    ExtraTools:       []kit.Tool{...},     // Add tools alongside defaults
+    DisableCoreTools: true,                // Use no core tools (0 tools, for chat-only)
+
+    // Configuration
+    SkipConfig:   true,                   // Skip .kit.yml files (viper defaults + env vars still apply)
 
     // Compaction
     AutoCompact:  true,                // Auto-compact near context limit
@@ -540,6 +561,28 @@ host, err := kit.New(ctx, &kit.Options{
 })
 ```
 
+### Custom Tools
+
+Create custom tools with automatic schema generation — no external dependencies needed:
+
+```go
+type SearchInput struct {
+    Query string `json:"query" description:"Search query"`
+}
+
+searchTool := kit.NewTool("search", "Search the codebase",
+    func(ctx context.Context, input SearchInput) (kit.ToolOutput, error) {
+        return kit.TextResult("Found: ..."), nil
+    },
+)
+
+host, _ := kit.New(ctx, &kit.Options{
+    ExtraTools: []kit.Tool{searchTool}, // adds alongside built-in tools
+})
+```
+
+Use `kit.NewParallelTool` for tools safe to run concurrently. See the [SDK docs](/sdk/overview) for full details on struct tags, `ToolOutput` fields, and `ToolCallIDFromContext`.
+
 ### With Callbacks
 
 ```go

cmd/root.go

@@ -7,10 +7,10 @@ import (
 	"image/color"
 	"log"
 	"os"
+	"path/filepath"
 	"strings"
 
 	tea "charm.land/bubbletea/v2"
-	"charm.land/lipgloss/v2"
 	"github.com/mark3labs/kit/internal/app"
 	"github.com/mark3labs/kit/internal/auth"
 	"github.com/mark3labs/kit/internal/config"
@@ -18,6 +18,9 @@ import (
 	"github.com/mark3labs/kit/internal/models"
 	"github.com/mark3labs/kit/internal/prompts"
 	"github.com/mark3labs/kit/internal/ui"
+	"github.com/mark3labs/kit/internal/ui/commands"
+	"github.com/mark3labs/kit/internal/ui/progress"
+	"github.com/mark3labs/kit/internal/watcher"
 	kit "github.com/mark3labs/kit/pkg/kit"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
@@ -31,13 +34,18 @@ var (
 	providerURL      string
 	providerAPIKey   string
 	debugMode        bool
-	positionalPrompt string // set by processPositionalArgs from CLI positional args
-	quietFlag        bool
-	jsonFlag         bool
-	noExitFlag       bool
-	maxSteps         int
-	streamFlag       bool // Enable streaming output
-	autoCompactFlag  bool // Enable auto-compaction near context limit
+	positionalPrompt string        // set by processPositionalArgs from CLI positional args
+	positionalFiles  []ui.FilePart // binary @file parts from processPositionalArgs
+
+	// MCP resource callbacks, set in runNormalMode, consumed by runInteractiveModeBubbleTea.
+	mcpGetResources   func() []ui.FileSuggestion
+	mcpResourceReader ui.MCPResourceReader
+	quietFlag         bool
+	jsonFlag          bool
+	noExitFlag        bool
+	maxSteps          int
+	streamFlag        bool // Enable streaming output
+	autoCompactFlag   bool // Enable auto-compaction near context limit
 
 	// Session management
 	sessionPath string
@@ -48,12 +56,14 @@ var (
 	noSessionFlag bool // --no-session: ephemeral mode, no persistence
 
 	// Model generation parameters
-	maxTokens     int
-	temperature   float32
-	topP          float32
-	topK          int32
-	stopSequences []string
-	thinkingLevel string
+	maxTokens        int
+	temperature      float32
+	topP             float32
+	topK             int32
+	frequencyPenalty float32
+	presencePenalty  float32
+	stopSequences    []string
+	thinkingLevel    string
 
 	// Ollama-specific parameters
 	numGPU  int32
@@ -154,6 +164,9 @@ func InitConfig() {
 		fmt.Fprintf(os.Stderr, "%v\n", err)
 		os.Exit(1)
 	}
+	// Rebuild the model registry now that viper has the config loaded,
+	// so customModels defined in the config file are picked up.
+	models.ReloadGlobalRegistry()
 }
 
 // LoadConfigWithEnvSubstitution loads a config file with environment variable
@@ -217,29 +230,10 @@ func configToUiTheme(cfg config.Theme) ui.Theme {
 	}
 }
 
-// kitBanner returns the KIT ASCII art title with KITT scanner lights,
-// rendered with a KITT red gradient.
+// kitBanner returns the KIT ASCII art title with KITT scanner lights.
+// Delegates to ui.KitBanner() which owns the logo rendering.
 func kitBanner() string {
-	kittDark := lipgloss.Color("#8B0000")
-	kittBright := lipgloss.Color("#FF2200")
-	lines := []string{
-		"            ██╗  ██╗ ██╗ ████████╗",
-		"            ██║ ██╔╝ ██║ ╚══██╔══╝",
-		"            █████╔╝  ██║    ██║",
-		"            ██╔═██╗  ██║    ██║",
-		"            ██║  ██╗ ██║    ██║",
-		"            ╚═╝  ╚═╝ ╚═╝    ╚═╝",
-		" ░░░░░░▒▒▒▒▒▓▓▓▓███████████████▓▓▓▓▒▒▒▒▒░░░░░░",
-	}
-
-	var result strings.Builder
-	for i, line := range lines {
-		if i > 0 {
-			result.WriteString("\n")
-		}
-		result.WriteString(ui.ApplyGradient(line, kittDark, kittBright))
-	}
-	return result.String()
+	return ui.KitBanner()
 }
 
 func init() {
@@ -307,6 +301,8 @@ func init() {
 	flags.Float32Var(&temperature, "temperature", 0.7, "controls randomness in responses (0.0-1.0)")
 	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.Float32Var(&frequencyPenalty, "frequency-penalty", 0.0, "penalizes tokens based on frequency of appearance (0.0-2.0)")
+	flags.Float32Var(&presencePenalty, "presence-penalty", 0.0, "penalizes tokens based on whether they have appeared (0.0-2.0)")
 	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")
 
@@ -329,6 +325,8 @@ func init() {
 	_ = viper.BindPFlag("temperature", rootCmd.PersistentFlags().Lookup("temperature"))
 	_ = viper.BindPFlag("top-p", rootCmd.PersistentFlags().Lookup("top-p"))
 	_ = viper.BindPFlag("top-k", rootCmd.PersistentFlags().Lookup("top-k"))
+	_ = viper.BindPFlag("frequency-penalty", rootCmd.PersistentFlags().Lookup("frequency-penalty"))
+	_ = viper.BindPFlag("presence-penalty", rootCmd.PersistentFlags().Lookup("presence-penalty"))
 	_ = 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"))
@@ -346,12 +344,14 @@ func init() {
 }
 
 // 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:
+// attachments and prompt text. Text file content is read and prepended to
+// positionalPrompt; binary files (images, audio) are stored in positionalFiles
+// for multimodal submission. Positional args are the primary way to run
+// non-interactive mode:
 //
 //	kit "Explain this codebase"
 //	kit @code.ts @test.ts "Review these files"
+//	kit @screenshot.png "What's in this image?"
 func processPositionalArgs(args []string) {
 	cwd, err := os.Getwd()
 	if err != nil {
@@ -370,14 +370,17 @@ func processPositionalArgs(args []string) {
 	}
 
 	// Build file content prefix from @file arguments.
+	// Text files are XML-wrapped inline; binary files become multimodal parts.
 	var fileContent strings.Builder
 	for _, token := range fileTokens {
-		expanded := ui.ProcessFileAttachments(token, cwd)
-		if expanded != token {
-			// File was resolved — add it.
-			fileContent.WriteString(expanded)
+		result := ui.ProcessFileAttachments(token, cwd)
+		if result.ProcessedText != token {
+			// Text file was resolved — add it.
+			fileContent.WriteString(result.ProcessedText)
 			fileContent.WriteString("\n\n")
 		}
+		// Collect binary file parts for multimodal submission.
+		positionalFiles = append(positionalFiles, result.FileParts...)
 	}
 
 	// Combine: positional prompt text is appended to any existing --prompt
@@ -406,21 +409,21 @@ func runKit(ctx context.Context) error {
 }
 
 // extensionCommandsForUI converts extension-registered CommandDefs into the
-// ui.ExtensionCommand type used by the interactive TUI. Command names are
+// commands.ExtensionCommand type used by the interactive TUI. Command names are
 // normalised to start with "/" so they integrate with the slash-command
 // autocomplete and dispatch pipeline.
-func extensionCommandsForUI(k *kit.Kit) []ui.ExtensionCommand {
+func extensionCommandsForUI(k *kit.Kit) []commands.ExtensionCommand {
 	defs := k.Extensions().Commands()
 	if len(defs) == 0 {
 		return nil
 	}
-	cmds := make([]ui.ExtensionCommand, 0, len(defs))
+	cmds := make([]commands.ExtensionCommand, 0, len(defs))
 	for _, d := range defs {
 		name := d.Name
 		if len(name) > 0 && name[0] != '/' {
 			name = "/" + name
 		}
-		ec := ui.ExtensionCommand{
+		ec := commands.ExtensionCommand{
 			Name:        name,
 			Description: d.Description,
 			Execute: func(args string) (string, error) {
@@ -733,18 +736,39 @@ func runNormalMode(ctx context.Context) error {
 
 	// Build Kit options from CLI flags and create the SDK instance.
 	// kit.New() handles: config → skills → agent → session → extension bridge.
+	authHandler, authErr := kit.NewCLIMCPAuthHandler()
+	if authErr != nil {
+		// Non-fatal: OAuth just won't be available for remote MCP servers.
+		fmt.Fprintf(os.Stderr, "Warning: Failed to create OAuth handler: %v\n", authErr)
+	}
+
+	// appInstancePtr is used to break the circular dependency between
+	// kit.New (which needs the OnMCPServerLoaded callback) and app.New
+	// (which is needed by the callback to send events to the TUI).
+	var appInstancePtr *app.App
+
 	kitOpts := &kit.Options{
-		Quiet:       quietFlag,
-		Debug:       debugMode,
-		NoSession:   noSessionFlag,
-		Continue:    continueFlag,
-		SessionPath: sessionPath,
-		AutoCompact: autoCompactFlag,
+		Quiet:          quietFlag,
+		Debug:          debugMode,
+		NoSession:      noSessionFlag,
+		Continue:       continueFlag,
+		SessionPath:    sessionPath,
+		AutoCompact:    autoCompactFlag,
+		MCPAuthHandler: authHandler,
+		// This callback is called when each MCP server finishes loading.
+		// We use a closure that captures appInstancePtr which is set after
+		// app.New() is called below.
+		OnMCPServerLoaded: func(serverName string, toolCount int, err error) {
+			if appInstancePtr != nil {
+				appInstancePtr.NotifyMCPServerLoaded(serverName, toolCount, err)
+			}
+		},
 		CLI: &kit.CLIOptions{
-			MCPConfig:         mcpConfig,
-			ShowSpinner:       true,
-			SpinnerFunc:       spinnerFunc,
-			UseBufferedLogger: true,
+			MCPConfig:          mcpConfig,
+			ShowSpinner:        true,
+			SpinnerFunc:        spinnerFunc,
+			UseBufferedLogger:  true,
+			ProgressReaderFunc: progress.NewProgressReadCloser,
 		},
 	}
 	if resumeFlag {
@@ -810,8 +834,16 @@ func runNormalMode(ctx context.Context) error {
 	}
 
 	appInstance := app.New(appOpts, messages)
+	appInstancePtr = appInstance // Wire up the MCP server loaded callback.
 	defer appInstance.Close()
 
+	// Wire OAuth handler to route messages through the TUI once it's running.
+	if authHandler != nil {
+		authHandler.NotifyFunc = func(serverName, message string) {
+			appInstance.PrintFromExtension("info", message)
+		}
+	}
+
 	// Buffer for extension messages during startup (printed after startup banner).
 	var startupExtensionMessages []string
 
@@ -835,7 +867,37 @@ func runNormalMode(ctx context.Context) error {
 			PrintBlock:    appInstance.PrintBlockFromExtension,
 			SendMessage:   func(text string) { appInstance.Run(text) },
 			CancelAndSend: func(text string) { appInstance.InterruptAndSend(text) },
-			Exit:          func() { appInstance.QuitFromExtension() },
+			Abort:         func() { appInstance.Abort() },
+			IsIdle:        func() bool { return !appInstance.IsBusy() },
+			Compact: func(cfg extensions.CompactConfig) error {
+				return appInstance.CompactAsync(cfg.CustomInstructions, cfg.OnComplete, cfg.OnError)
+			},
+			SendMultimodalMessage: func(text string, files []extensions.FilePart) {
+				parts := make([]kit.LLMFilePart, len(files))
+				for i, f := range files {
+					parts[i] = kit.LLMFilePart{
+						Filename:  f.Filename,
+						Data:      f.Data,
+						MediaType: f.MediaType,
+					}
+				}
+				appInstance.RunWithFiles(text, parts)
+			},
+			GetSessionUsage: func() extensions.SessionUsage {
+				if usageTracker == nil {
+					return extensions.SessionUsage{}
+				}
+				stats := usageTracker.GetSessionStats()
+				return extensions.SessionUsage{
+					TotalInputTokens:      stats.TotalInputTokens,
+					TotalOutputTokens:     stats.TotalOutputTokens,
+					TotalCacheReadTokens:  stats.TotalCacheReadTokens,
+					TotalCacheWriteTokens: stats.TotalCacheWriteTokens,
+					TotalCost:             stats.TotalCost,
+					RequestCount:          stats.RequestCount,
+				}
+			},
+			Exit: func() { appInstance.QuitFromExtension() },
 			SetWidget: func(config extensions.WidgetConfig) {
 				kitInstance.Extensions().SetWidget(config)
 				go appInstance.NotifyWidgetUpdate()
@@ -1256,7 +1318,37 @@ func runNormalMode(ctx context.Context) error {
 			PrintBlock:    appInstance.PrintBlockFromExtension,
 			SendMessage:   func(text string) { appInstance.Run(text) },
 			CancelAndSend: func(text string) { appInstance.InterruptAndSend(text) },
-			Exit:          func() { appInstance.QuitFromExtension() },
+			Abort:         func() { appInstance.Abort() },
+			IsIdle:        func() bool { return !appInstance.IsBusy() },
+			Compact: func(cfg extensions.CompactConfig) error {
+				return appInstance.CompactAsync(cfg.CustomInstructions, cfg.OnComplete, cfg.OnError)
+			},
+			SendMultimodalMessage: func(text string, files []extensions.FilePart) {
+				parts := make([]kit.LLMFilePart, len(files))
+				for i, f := range files {
+					parts[i] = kit.LLMFilePart{
+						Filename:  f.Filename,
+						Data:      f.Data,
+						MediaType: f.MediaType,
+					}
+				}
+				appInstance.RunWithFiles(text, parts)
+			},
+			GetSessionUsage: func() extensions.SessionUsage {
+				if usageTracker == nil {
+					return extensions.SessionUsage{}
+				}
+				stats := usageTracker.GetSessionStats()
+				return extensions.SessionUsage{
+					TotalInputTokens:      stats.TotalInputTokens,
+					TotalOutputTokens:     stats.TotalOutputTokens,
+					TotalCacheReadTokens:  stats.TotalCacheReadTokens,
+					TotalCacheWriteTokens: stats.TotalCacheWriteTokens,
+					TotalCost:             stats.TotalCost,
+					RequestCount:          stats.RequestCount,
+				}
+			},
+			Exit: func() { appInstance.QuitFromExtension() },
 			SetWidget: func(config extensions.WidgetConfig) {
 				kitInstance.Extensions().SetWidget(config)
 				go appInstance.NotifyWidgetUpdate()
@@ -1556,6 +1648,49 @@ func runNormalMode(ctx context.Context) error {
 		})
 	}
 
+	// Build prompt template and skill item provider callbacks for hot-reload.
+	// These are called by the TUI when ContentReloadEvent fires.
+	getPromptTemplates := func() []*prompts.PromptTemplate {
+		if noPromptTemplates {
+			return nil
+		}
+		homeDir, _ := os.UserHomeDir()
+		cwd, _ := os.Getwd()
+		tpls, _, err := prompts.LoadAll(prompts.LoadOptions{
+			Cwd:             cwd,
+			HomeDir:         homeDir,
+			ExtraPaths:      promptTemplatePaths,
+			ConfigPaths:     viper.GetStringSlice("prompts"),
+			IncludeDefaults: true,
+		})
+		if err != nil {
+			log.Printf("Warning: failed to reload prompt templates: %v", err)
+		}
+		return tpls
+	}
+
+	getSkillItems := func() []ui.SkillItem {
+		// Re-discover skills from disk.
+		if err := kitInstance.ReloadSkills(); err != nil {
+			log.Printf("Warning: failed to reload skills: %v", err)
+			return nil
+		}
+		cwd, _ := os.Getwd()
+		var items []ui.SkillItem
+		for _, s := range kitInstance.GetSkills() {
+			source := "user"
+			if strings.HasPrefix(s.Path, cwd) {
+				source = "project"
+			}
+			items = append(items, ui.SkillItem{
+				Name:   s.Name,
+				Path:   s.Path,
+				Source: source,
+			})
+		}
+		return items
+	}
+
 	// Build extension UI providers once (shared between both modes).
 	getWidgets := widgetProviderForUI(kitInstance)
 	getHeader := headerProviderForUI(kitInstance)
@@ -1567,10 +1702,104 @@ func runNormalMode(ctx context.Context) error {
 	emitBeforeFork := beforeForkProviderForUI(kitInstance)
 	emitBeforeSessionSwitch := beforeSessionSwitchProviderForUI(kitInstance)
 	getGlobalShortcuts := globalShortcutsProviderForUI(kitInstance)
-	getExtensionCommands := func() []ui.ExtensionCommand {
+	getExtensionCommands := func() []commands.ExtensionCommand {
 		return extensionCommandsForUI(kitInstance)
 	}
 
+	// Build dynamic tool name and MCP tool count providers. These are called
+	// by the TUI when MCPToolsReadyEvent fires to refresh the /tools list
+	// and startup info bar after background MCP tool loading completes.
+	getToolNames := func() []string {
+		return kitInstance.GetToolNames()
+	}
+	getMCPToolCount := func() int {
+		return kitInstance.GetMCPToolCount()
+	}
+
+	// Build MCP prompt provider callbacks for the TUI.
+	// Convert kit.MCPPrompt → ui.MCPPromptInfo for the UI layer.
+	convertMCPPromptsForUI := func() []ui.MCPPromptInfo {
+		prompts := kitInstance.ListMCPPrompts()
+		if len(prompts) == 0 {
+			return nil
+		}
+		result := make([]ui.MCPPromptInfo, len(prompts))
+		for i, p := range prompts {
+			args := make([]ui.MCPPromptArgInfo, len(p.Arguments))
+			for j, a := range p.Arguments {
+				args[j] = ui.MCPPromptArgInfo{
+					Name:        a.Name,
+					Description: a.Description,
+					Required:    a.Required,
+				}
+			}
+			result[i] = ui.MCPPromptInfo{
+				Name:        p.Name,
+				Description: p.Description,
+				Arguments:   args,
+				ServerName:  p.ServerName,
+			}
+		}
+		return result
+	}
+	mcpPrompts := convertMCPPromptsForUI()
+	getMCPPrompts := func() []ui.MCPPromptInfo {
+		return convertMCPPromptsForUI()
+	}
+	expandMCPPrompt := func(serverName, promptName string, args map[string]string) (*ui.MCPPromptExpandResult, error) {
+		result, err := kitInstance.GetMCPPrompt(context.Background(), serverName, promptName, args)
+		if err != nil {
+			return nil, err
+		}
+		msgs := make([]ui.MCPPromptMessageInfo, len(result.Messages))
+		for i, m := range result.Messages {
+			msgs[i] = ui.MCPPromptMessageInfo{
+				Role:      m.Role,
+				Content:   m.Content,
+				FileParts: m.FileParts,
+			}
+		}
+		return &ui.MCPPromptExpandResult{Messages: msgs}, nil
+	}
+
+	// MCP resource callbacks for @ autocomplete and submit-time resolution.
+	getMCPResources := func() []ui.FileSuggestion {
+		resources := kitInstance.ListMCPResources()
+		suggestions := make([]ui.FileSuggestion, len(resources))
+		for i, r := range resources {
+			suggestions[i] = ui.FileSuggestion{
+				RelPath:        r.Name,
+				IsMCPResource:  true,
+				MCPServerName:  r.ServerName,
+				MCPResourceURI: r.URI,
+				MCPMIMEType:    r.MIMEType,
+				Score:          100, // default score, filtered later
+			}
+		}
+		return suggestions
+	}
+	mcpResourceReaderFn := func(serverName, uri string) (string, []byte, string, bool, error) {
+		content, err := kitInstance.ReadMCPResource(context.Background(), serverName, uri)
+		if err != nil {
+			return "", nil, "", false, err
+		}
+		return content.Text, content.BlobData, content.MIMEType, content.IsBlob, nil
+	}
+
+	// Store MCP resource callbacks at package level for consumption by
+	// runInteractiveModeBubbleTea and runNonInteractiveModeApp.
+	mcpGetResources = getMCPResources
+	mcpResourceReader = mcpResourceReaderFn
+
+	// Start a goroutine that waits for background MCP tool loading to
+	// complete and notifies the TUI so it can refresh tool names and counts.
+	if len(mcpConfig.MCPServers) > 0 {
+		go func() {
+			_ = kitInstance.WaitForMCPTools()
+			appInstance.NotifyMCPToolsReady()
+		}()
+	}
+
 	// Build model switching callbacks for the /model command.
 	setModelForUI := func(modelString string) error {
 		err := kitInstance.SetModel(context.Background(), modelString)
@@ -1624,9 +1853,81 @@ func runNormalMode(ctx context.Context) error {
 		return nil
 	}
 
+	// Build extension reload callback for the /reload-ext command.
+	reloadExtensionsForUI := func() error {
+		err := kitInstance.Extensions().Reload()
+		if err != nil {
+			return err
+		}
+		go appInstance.NotifyWidgetUpdate()
+		return nil
+	}
+
+	// Start file watcher for automatic extension hot-reload.
+	extraPaths := viper.GetStringSlice("extension")
+	watchDirs := extensions.WatchedDirs(extraPaths)
+	if len(watchDirs) > 0 {
+		extWatcher, watchErr := extensions.NewWatcher(watchDirs, func() {
+			if err := reloadExtensionsForUI(); err != nil {
+				log.Printf("auto-reload extensions failed: %v", err)
+			}
+		})
+		if watchErr != nil {
+			log.Printf("extension file watcher not started: %v", watchErr)
+		} else {
+			go extWatcher.Start(ctx)
+			defer func() { _ = extWatcher.Close() }()
+		}
+	}
+
+	// Start file watchers for automatic prompt and skill hot-reload.
+	{
+		homeDir, _ := os.UserHomeDir()
+		cwd, _ := os.Getwd()
+
+		// Collect prompt template directories.
+		promptDirs := watcher.CollectDirs(
+			[]string{
+				filepath.Join(homeDir, ".kit", "prompts"),
+				filepath.Join(cwd, ".kit", "prompts"),
+			},
+			append(promptTemplatePaths, viper.GetStringSlice("prompts")...),
+		)
+
+		// Collect skill directories.
+		skillDirs := watcher.CollectDirs(
+			[]string{
+				filepath.Join(homeDir, ".config", "kit", "skills"),
+				filepath.Join(cwd, ".agents", "skills"),
+				filepath.Join(cwd, ".kit", "skills"),
+			},
+			nil,
+		)
+
+		// Combine all content directories and start a single watcher.
+		allContentDirs := append(promptDirs, skillDirs...)
+		if len(allContentDirs) > 0 {
+			contentWatcher, watchErr := watcher.New(watcher.Options{
+				Dirs:       allContentDirs,
+				Extensions: []string{".md", ".txt"},
+				Label:      "prompts/skills",
+				OnReload: func() {
+					log.Printf("auto-reloading prompts and skills")
+					appInstance.NotifyContentReload()
+				},
+			})
+			if watchErr != nil {
+				log.Printf("content file watcher not started: %v", watchErr)
+			} else {
+				go contentWatcher.Start(ctx)
+				defer func() { _ = contentWatcher.Close() }()
+			}
+		}
+	}
+
 	// Check if running in non-interactive mode
 	if positionalPrompt != "" {
-		return runNonInteractiveModeApp(ctx, appInstance, cli, positionalPrompt, quietFlag, jsonFlag, noExitFlag, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, promptTemplates, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModelForUI, emitModelChangeForUI, kitInstance.IsReasoningModel(), kitInstance.GetThinkingLevel(), setThinkingLevelForUI, switchSessionForUI)
+		return runNonInteractiveModeApp(ctx, appInstance, cli, positionalPrompt, quietFlag, jsonFlag, noExitFlag, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, promptTemplates, contextPaths, skillItems, getPromptTemplates, getSkillItems, getToolNames, getMCPToolCount, mcpPrompts, getMCPPrompts, expandMCPPrompt, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModelForUI, emitModelChangeForUI, kitInstance.IsReasoningModel(), kitInstance.GetThinkingLevel(), setThinkingLevelForUI, switchSessionForUI, reloadExtensionsForUI)
 	}
 
 	// Quiet mode is not allowed in interactive mode
@@ -1634,7 +1935,7 @@ func runNormalMode(ctx context.Context) error {
 		return fmt.Errorf("--quiet requires a prompt")
 	}
 
-	return runInteractiveModeBubbleTea(ctx, appInstance, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, promptTemplates, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModelForUI, emitModelChangeForUI, kitInstance.IsReasoningModel(), kitInstance.GetThinkingLevel(), setThinkingLevelForUI, switchSessionForUI, startupExtensionMessages)
+	return runInteractiveModeBubbleTea(ctx, appInstance, modelName, parsedProvider, kitInstance.GetLoadingMessage(), serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, promptTemplates, contextPaths, skillItems, getPromptTemplates, getSkillItems, getToolNames, getMCPToolCount, mcpPrompts, getMCPPrompts, expandMCPPrompt, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModelForUI, emitModelChangeForUI, kitInstance.IsReasoningModel(), kitInstance.GetThinkingLevel(), setThinkingLevelForUI, switchSessionForUI, reloadExtensionsForUI, startupExtensionMessages)
 }
 
 // runNonInteractiveModeApp executes a single prompt via the app layer and exits,
@@ -1647,15 +1948,33 @@ 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, promptTemplates []*prompts.PromptTemplate, 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, switchSession func(string) error) 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 []commands.ExtensionCommand, promptTemplates []*prompts.PromptTemplate, contextPaths []string, skillItems []ui.SkillItem, getPromptTemplates func() []*prompts.PromptTemplate, getSkillItems func() []ui.SkillItem, getToolNames func() []string, getMCPToolCount func() int, mcpPrompts []ui.MCPPromptInfo, getMCPPrompts func() []ui.MCPPromptInfo, expandMCPPrompt func(string, string, map[string]string) (*ui.MCPPromptExpandResult, error), 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() []commands.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error, switchSession func(string) error, reloadExtensions func() error) error {
 	// Expand @file references in the prompt before sending to the agent.
+	// Text files are XML-inlined; binary files are extracted as multimodal parts.
+	var fileParts []kit.LLMFilePart
 	if cwd, err := os.Getwd(); err == nil {
-		prompt = ui.ProcessFileAttachments(prompt, cwd)
+		result := ui.ProcessFileAttachments(prompt, cwd, mcpResourceReader)
+		prompt = result.ProcessedText
+		for _, fp := range result.FileParts {
+			fileParts = append(fileParts, kit.LLMFilePart{
+				Filename:  fp.Filename,
+				Data:      fp.Data,
+				MediaType: fp.MediaType,
+			})
+		}
+	}
+	// Also include binary files from processPositionalArgs (CLI @file args).
+	for _, fp := range positionalFiles {
+		fileParts = append(fileParts, kit.LLMFilePart{
+			Filename:  fp.Filename,
+			Data:      fp.Data,
+			MediaType: fp.MediaType,
+		})
 	}
 
 	if jsonOutput {
 		// JSON mode: no intermediate display, structured JSON output.
-		result, err := appInstance.RunOnceResult(ctx, prompt)
+		result, err := appInstance.RunOnceResultWithFiles(ctx, prompt, fileParts)
 		if err != nil {
 			writeJSONError(err)
 			return err
@@ -1667,7 +1986,7 @@ func runNonInteractiveModeApp(ctx context.Context, appInstance *app.App, cli *ui
 		fmt.Println(string(data))
 	} else if quiet {
 		// Quiet mode: no intermediate display, just print final response.
-		if err := appInstance.RunOnce(ctx, prompt); err != nil {
+		if err := appInstance.RunOnceWithFiles(ctx, prompt, fileParts); err != nil {
 			return err
 		}
 	} else if cli != nil {
@@ -1676,21 +1995,21 @@ func runNonInteractiveModeApp(ctx context.Context, appInstance *app.App, cli *ui
 
 		// Route events through the shared CLI event handler.
 		eventHandler := ui.NewCLIEventHandler(cli, modelName)
-		err := appInstance.RunOnceWithDisplay(ctx, prompt, eventHandler.Handle)
+		err := appInstance.RunOnceWithDisplayAndFiles(ctx, prompt, eventHandler.Handle, fileParts)
 		eventHandler.Cleanup()
 		if err != nil {
 			return err
 		}
 	} else {
 		// No CLI available (shouldn't happen in non-quiet mode, but be safe).
-		if err := appInstance.RunOnce(ctx, prompt); err != nil {
+		if err := appInstance.RunOnceWithFiles(ctx, prompt, fileParts); err != nil {
 			return err
 		}
 	}
 
 	// 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, promptTemplates, contextPaths, skillItems, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModel, emitModelChange, isReasoningModel, thinkingLevel, setThinkingLevel, switchSession, nil)
+		return runInteractiveModeBubbleTea(ctx, appInstance, modelName, providerName, loadingMessage, serverNames, toolNames, mcpToolCount, extensionToolCount, usageTracker, extCommands, promptTemplates, contextPaths, skillItems, getPromptTemplates, getSkillItems, getToolNames, getMCPToolCount, mcpPrompts, getMCPPrompts, expandMCPPrompt, getWidgets, getHeader, getFooter, getToolRenderer, getEditorInterceptor, getUIVisibility, getStatusBarEntries, emitBeforeFork, emitBeforeSessionSwitch, getGlobalShortcuts, getExtensionCommands, setModel, emitModelChange, isReasoningModel, thinkingLevel, setThinkingLevel, switchSession, reloadExtensions, nil)
 	}
 
 	return nil
@@ -1788,7 +2107,19 @@ 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, promptTemplates []*prompts.PromptTemplate, 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, switchSession func(string) error, startupExtensionMessages []string) error {
+func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []commands.ExtensionCommand, promptTemplates []*prompts.PromptTemplate, contextPaths []string, skillItems []ui.SkillItem, getPromptTemplates func() []*prompts.PromptTemplate, getSkillItems func() []ui.SkillItem, getToolNames func() []string, getMCPToolCount func() int, mcpPrompts []ui.MCPPromptInfo, getMCPPrompts func() []ui.MCPPromptInfo, expandMCPPrompt func(string, string, map[string]string) (*ui.MCPPromptExpandResult, error), 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() []commands.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error, switchSession func(string) error, reloadExtensions func() error, startupExtensionMessages []string) error {
+	// Redirect all log output (stdlib and charm) to a file so that log
+	// messages don't write to stderr and corrupt the TUI. Bubble Tea
+	// captures stdout for rendering; any stray stderr output from
+	// background goroutines (watchers, extension handlers, SDK internals)
+	// will visually corrupt the terminal.
+	logDir := filepath.Join(os.TempDir(), "kit")
+	_ = os.MkdirAll(logDir, 0o700)
+	logFile, logErr := tea.LogToFile(filepath.Join(logDir, "kit.log"), "kit")
+	if logErr == nil {
+		defer func() { _ = logFile.Close() }()
+	}
+
 	// Determine terminal size; fall back gracefully.
 	termWidth, termHeight, err := term.GetSize(int(os.Stdout.Fd()))
 	if err != nil || termWidth == 0 {
@@ -1807,13 +2138,20 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 		Height:                   termHeight,
 		ServerNames:              serverNames,
 		ToolNames:                toolNames,
+		GetToolNames:             getToolNames,
+		GetMCPToolCount:          getMCPToolCount,
 		MCPToolCount:             mcpToolCount,
 		ExtensionToolCount:       extensionToolCount,
 		UsageTracker:             usageTracker,
 		ExtensionCommands:        extCommands,
 		PromptTemplates:          promptTemplates,
+		GetPromptTemplates:       getPromptTemplates,
+		MCPPrompts:               mcpPrompts,
+		GetMCPPrompts:            getMCPPrompts,
+		ExpandMCPPrompt:          expandMCPPrompt,
 		ContextPaths:             contextPaths,
 		SkillItems:               skillItems,
+		GetSkillItems:            getSkillItems,
 		StartupExtensionMessages: startupExtensionMessages,
 		GetWidgets:               getWidgets,
 		GetHeader:                getHeader,
@@ -1832,23 +2170,12 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 		IsReasoningModel:         isReasoningModel,
 		SetThinkingLevel:         setThinkingLevel,
 		SwitchSession:            switchSession,
+		ReloadExtensions:         reloadExtensions,
 		ShowSessionPicker:        resumeFlag,
+		GetMCPResources:          mcpGetResources,
+		MCPResourceReader:        mcpResourceReader,
 	})
 
-	// Print KIT banner and startup info to stdout before Bubble Tea takes over the screen.
-	fmt.Println(kitBanner())
-	fmt.Println()
-	appModel.PrintStartupInfo()
-
-	// Print any extension messages that were captured during startup.
-	if len(startupExtensionMessages) > 0 {
-		fmt.Println()
-		for _, msg := range startupExtensionMessages {
-			fmt.Println(msg)
-		}
-		fmt.Println()
-	}
-
 	program := tea.NewProgram(appModel)
 
 	// Register the program with the app layer so agent events are sent to the TUI.

examples/extensions/dev-reload.go

@@ -7,10 +7,12 @@
 // development: edit your extension source, then type /reload to pick up
 // changes immediately.
 //
-// Event handlers, slash commands, tool renderers, message renderers, and
-// keyboard shortcuts update immediately. Extension-defined tools are NOT
-// updated (they are baked into the agent at creation time and require a
-// restart).
+// Note: Extensions in autoloaded directories (~/.config/kit/extensions/
+// and .kit/extensions/) are automatically reloaded on save. The /reload
+// command is useful for extensions loaded via -e from other locations.
+//
+// Event handlers, slash commands, tool definitions, tool renderers,
+// message renderers, and keyboard shortcuts all update immediately.
 //
 // Commands:
 //   /reload   — hot-reload all extensions from disk

examples/extensions/inline-bash.go

@@ -10,13 +10,21 @@ import (
 	"kit/ext"
 )
 
+// re matches !{...} with non-greedy content.
+var re = regexp.MustCompile(`!\{([^}]+)\}`)
+
 // Init expands inline bash expressions in user prompts before they reach the
-// LLM. Text like !{git branch --show-current} is replaced with the command's
-// stdout.
+// LLM. Text like !{git rev-parse --abbrev-ref HEAD} is replaced with the
+// command's stdout.
+//
+// In interactive mode the expansion happens at submit time via an editor
+// interceptor, so the expanded text is also visible in the user message
+// block on screen. In non-interactive mode (CLI, script, queue) the
+// expansion happens via OnInput transform.
 //
 // Examples:
 //
-//	"Fix the tests on !{git branch --show-current}"
+//	"Fix the tests on !{git rev-parse --abbrev-ref HEAD}"
 //	  → "Fix the tests on main"
 //
 //	"The current directory is !{pwd}"
@@ -24,29 +32,59 @@ import (
 //
 // Usage: kit -e examples/extensions/inline-bash.go
 func Init(api ext.API) {
-	// Matches !{...} with non-greedy content.
-	re := regexp.MustCompile(`!\{([^}]+)\}`)
+	// ── Interactive mode: editor interceptor ──────────────────────────
+	// Intercept Enter / Ctrl+D so we can expand !{...} BEFORE the
+	// SubmitMsg is created. This ensures the expanded text appears in
+	// the user message block on screen as well as in the LLM prompt.
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		if !ctx.Interactive {
+			return
+		}
+		ctx.SetEditor(ext.EditorConfig{
+			HandleKey: func(key string, currentText string) ext.EditorKeyAction {
+				if (key == "enter" || key == "ctrl+d") && re.MatchString(currentText) {
+					expanded := expand(currentText)
+					// Clear the textarea asynchronously — calling
+					// SetEditorText synchronously from inside Update()
+					// would deadlock the BubbleTea event loop.
+					go ctx.SetEditorText("")
+					return ext.EditorKeyAction{
+						Type:       ext.EditorKeySubmit,
+						SubmitText: expanded,
+					}
+				}
+				return ext.EditorKeyAction{Type: ext.EditorKeyPassthrough}
+			},
+		})
+	})
 
+	// ── Non-interactive fallback: OnInput transform ──────────────────
+	// For CLI, script, and queue sources the editor interceptor is not
+	// active, so we fall back to OnInput which still rewrites the
+	// prompt text sent to the LLM.
 	api.OnInput(func(ev ext.InputEvent, ctx ext.Context) *ext.InputResult {
-		if !re.MatchString(ev.Text) {
+		if ev.Source == "interactive" || !re.MatchString(ev.Text) {
 			return nil
 		}
 
-		expanded := re.ReplaceAllStringFunc(ev.Text, func(match string) string {
-			// Extract the command between !{ and }.
-			cmd := re.FindStringSubmatch(match)[1]
-			cmd = strings.TrimSpace(cmd)
-
-			out, err := exec.Command("bash", "-c", cmd).Output()
-			if err != nil {
-				return match // keep original on error
-			}
-			return strings.TrimSpace(string(out))
-		})
-
 		return &ext.InputResult{
 			Action: "transform",
-			Text:   expanded,
+			Text:   expand(ev.Text),
 		}
 	})
 }
+
+// expand replaces every !{cmd} in text with the command's stdout.
+// On error the original !{cmd} token is preserved.
+func expand(text string) string {
+	return re.ReplaceAllStringFunc(text, func(match string) string {
+		cmd := re.FindStringSubmatch(match)[1]
+		cmd = strings.TrimSpace(cmd)
+
+		out, err := exec.Command("bash", "-c", cmd).Output()
+		if err != nil {
+			return match // keep original on error
+		}
+		return strings.TrimSpace(string(out))
+	})
+}

examples/extensions/kit-telegram/main.go

@@ -168,6 +168,10 @@ var (
 	// Test
 	pendingTest *PendingTest
 
+	// Typing indicator
+	typingTicker *time.Ticker
+	typingStop   chan struct{}
+
 	// Latest context for background goroutines
 	latestCtx    ext.Context
 	latestCtxSet bool
@@ -203,8 +207,23 @@ func configDir() string {
 	return filepath.Join(home, ".config", "kit")
 }
 
+func globalConfigDir() string {
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".config", "kit")
+}
+
 func configPath() string {
-	return filepath.Join(configDir(), "kit-telegram.json")
+	// Prefer project-local config, fall back to global config.
+	local := filepath.Join(configDir(), "kit-telegram.json")
+	if _, err := os.Stat(local); err == nil {
+		return local
+	}
+	global := filepath.Join(globalConfigDir(), "kit-telegram.json")
+	if _, err := os.Stat(global); err == nil {
+		return global
+	}
+	// Neither exists — return local path (will be created on connect).
+	return local
 }
 
 func failureLogDir() string {
@@ -387,6 +406,14 @@ func tgEditMessageText(token string, chatID int64, messageID int, text string) (
 	return &msg, nil
 }
 
+func tgSendChatAction(token string, chatID int64, action string) error {
+	_, err := telegramRequest(token, "sendChatAction", map[string]any{
+		"chat_id": chatID,
+		"action":  action,
+	}, 15)
+	return err
+}
+
 // ──────────────────────────────────────────────
 // Error classification
 // ──────────────────────────────────────────────
@@ -637,6 +664,48 @@ func clearHealthTimer() {
 	}
 }
 
+// ──────────────────────────────────────────────
+// Typing indicator
+// ──────────────────────────────────────────────
+
+func startTypingLoop() {
+	mu.Lock()
+	defer mu.Unlock()
+	if typingTicker != nil {
+		return
+	}
+	cfg := config
+	if cfg == nil || !cfg.Enabled {
+		return
+	}
+	token := cfg.BotToken
+	chatID := cfg.ChatID
+	typingTicker = time.NewTicker(4 * time.Second)
+	typingStop = make(chan struct{})
+	// Send immediately, then every 4 seconds.
+	go func() {
+		tgSendChatAction(token, chatID, "typing")
+		for {
+			select {
+			case <-typingTicker.C:
+				tgSendChatAction(token, chatID, "typing")
+			case <-typingStop:
+				return
+			}
+		}
+	}()
+}
+
+func stopTypingLoop() {
+	mu.Lock()
+	defer mu.Unlock()
+	if typingTicker != nil {
+		typingTicker.Stop()
+		close(typingStop)
+		typingTicker = nil
+	}
+}
+
 // ──────────────────────────────────────────────
 // Polling lifecycle
 // ──────────────────────────────────────────────
@@ -2105,6 +2174,7 @@ func Init(api ext.API) {
 		mu.Unlock()
 
 		sendShutdownDisconnectedMessage()
+		stopTypingLoop()
 		stopPolling()
 		clearHealthTimer()
 		clearFooter()
@@ -2128,6 +2198,7 @@ func Init(api ext.API) {
 		mu.Unlock()
 
 		report("run.start", fmt.Sprintf("runId=%d", run.ID))
+		startTypingLoop()
 		ensureProgressMessage()
 		updateProgressMessage()
 	})
@@ -2140,6 +2211,8 @@ func Init(api ext.API) {
 		run := activeRun
 		mu.Unlock()
 
+		stopTypingLoop()
+
 		if run != nil {
 			// Capture final response from event
 			if e.Response != "" {

go.mod

@@ -1,40 +1,46 @@
 module github.com/mark3labs/kit
 
-go 1.26.1
+go 1.26.2
 
 require (
 	charm.land/bubbles/v2 v2.1.0
-	charm.land/bubbletea/v2 v2.0.2
-	charm.land/fantasy v0.17.1
+	charm.land/bubbletea/v2 v2.0.5
+	charm.land/fantasy v0.17.2
 	charm.land/huh/v2 v2.0.3
-	charm.land/lipgloss/v2 v2.0.2
+	charm.land/lipgloss/v2 v2.0.3
 	github.com/alecthomas/chroma/v2 v2.23.1
+	github.com/atotto/clipboard v0.1.4
 	github.com/aymanbagabas/go-udiff v0.4.1
 	github.com/charmbracelet/fang v1.0.0
 	github.com/charmbracelet/log v1.0.0
+	github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266
+	github.com/charmbracelet/ultraviolet v0.0.0-20260414011438-8c69ec811b1e
+	github.com/charmbracelet/x/editor v0.2.0
+	github.com/clipperhouse/displaywidth v0.11.0
+	github.com/clipperhouse/uax29/v2 v2.7.0
 	github.com/coder/acp-go-sdk v0.6.3
-	github.com/indaco/herald v0.10.0
-	github.com/indaco/herald-md v0.1.0
-	github.com/mark3labs/mcp-go v0.46.0
+	github.com/fsnotify/fsnotify v1.9.0
+	github.com/indaco/herald v0.13.0
+	github.com/indaco/herald-md v0.3.0
+	github.com/mark3labs/mcp-go v0.48.0
 	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.41.0
+	golang.org/x/term v0.42.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
 	cloud.google.com/go v0.123.0 // indirect
-	cloud.google.com/go/auth v0.19.0 // indirect
+	cloud.google.com/go/auth v0.20.0 // indirect
 	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
 	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/atotto/clipboard v0.1.4 // indirect
+	github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0 // indirect
 	github.com/aws/aws-sdk-go-v2 v1.41.5 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 // indirect
-	github.com/aws/aws-sdk-go-v2/config v1.32.13 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.13 // indirect
+	github.com/aws/aws-sdk-go-v2/config v1.32.14 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.14 // indirect
 	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 // indirect
@@ -42,50 +48,44 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 // indirect
 	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 // indirect
 	github.com/aws/aws-sdk-go-v2/service/signin v1.0.9 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.14 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.18 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.15 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sts v1.41.10 // indirect
-	github.com/aws/smithy-go v1.24.2 // indirect
+	github.com/aws/smithy-go v1.24.3 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/charmbracelet/anthropic-sdk-go v0.0.0-20260223140439-63879b0b8dab // indirect
 	github.com/charmbracelet/colorprofile v0.4.3 // indirect
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 // indirect
-	github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266 // indirect
-	github.com/charmbracelet/ultraviolet v0.0.0-20260330092749-0f94982c930b // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
-	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260330094520-2dce04b6f8a4 // indirect
+	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260413165052-6921c759c913 // indirect
 	github.com/charmbracelet/x/exp/ordered v0.1.0 // indirect
-	github.com/charmbracelet/x/exp/slice v0.0.0-20260330094520-2dce04b6f8a4 // indirect
+	github.com/charmbracelet/x/exp/slice v0.0.0-20260413165052-6921c759c913 // indirect
 	github.com/charmbracelet/x/exp/strings v0.1.0 // 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/dlclark/regexp2 v1.11.5 // indirect
 	github.com/dustin/go-humanize v1.0.1 // 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.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
 	github.com/goccy/go-yaml v1.19.2 // indirect
-	github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/jsonschema-go v0.4.2 // 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.14 // indirect
-	github.com/googleapis/gax-go/v2 v2.20.0 // indirect
+	github.com/googleapis/gax-go/v2 v2.21.0 // indirect
 	github.com/gorilla/websocket v1.5.3 // indirect
-	github.com/kaptinlin/go-i18n v0.3.0 // indirect
+	github.com/kaptinlin/go-i18n v0.4.0 // indirect
 	github.com/kaptinlin/jsonpointer v0.4.17 // indirect
 	github.com/kaptinlin/jsonschema v0.7.7 // indirect
-	github.com/kaptinlin/messageformat-go v0.4.19 // indirect
+	github.com/kaptinlin/messageformat-go v0.4.20 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
 	github.com/muesli/mango v0.2.0 // indirect
 	github.com/muesli/mango-cobra v1.3.0 // indirect
@@ -104,38 +104,38 @@ require (
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/yuin/goldmark v1.8.2 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 // indirect
-	go.opentelemetry.io/otel v1.42.0 // indirect
-	go.opentelemetry.io/otel/metric v1.42.0 // indirect
-	go.opentelemetry.io/otel/trace v1.42.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.68.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.49.0 // indirect
-	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 // indirect
-	golang.org/x/net v0.52.0 // indirect
+	golang.org/x/crypto v0.50.0 // indirect
+	golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f // indirect
+	golang.org/x/net v0.53.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	google.golang.org/api v0.273.0 // indirect
-	google.golang.org/genai v1.52.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7 // indirect
-	google.golang.org/grpc v1.79.3 // indirect
+	google.golang.org/api v0.275.0 // indirect
+	google.golang.org/genai v1.54.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 // indirect
+	google.golang.org/grpc v1.80.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )
 
 require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
-	github.com/charmbracelet/x/ansi v0.11.6
+	github.com/charmbracelet/x/ansi v0.11.7
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/mattn/go-runewidth v0.0.21 // indirect
+	github.com/mattn/go-isatty v0.0.21 // indirect
+	github.com/mattn/go-runewidth v0.0.23 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
-	golang.org/x/text v0.35.0
+	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/text v0.36.0
 )

go.sum

@@ -1,29 +1,29 @@
 charm.land/bubbles/v2 v2.1.0 h1:YSnNh5cPYlYjPxRrzs5VEn3vwhtEn3jVGRBT3M7/I0g=
 charm.land/bubbles/v2 v2.1.0/go.mod h1:l97h4hym2hvWBVfmJDtrEHHCtkIKeTEb3TTJ4ZOB3wY=
-charm.land/bubbletea/v2 v2.0.2 h1:4CRtRnuZOdFDTWSff9r8QFt/9+z6Emubz3aDMnf/dx0=
-charm.land/bubbletea/v2 v2.0.2/go.mod h1:3LRff2U4WIYXy7MTxfbAQ+AdfM3D8Xuvz2wbsOD9OHQ=
-charm.land/fantasy v0.17.1 h1:SQzfnyJPDuQWt6e//KKmQmEEXdqHMC0IZz10XwkLcEM=
-charm.land/fantasy v0.17.1/go.mod h1:FF5ALCCHETacHJPBqU42CtwMInYQ0ul52fdzIHQMbQk=
+charm.land/bubbletea/v2 v2.0.5 h1:TQlLFqxo39AAHSVuOhJ5D3nH7O9Nk8JGinsfWQ4y1U4=
+charm.land/bubbletea/v2 v2.0.5/go.mod h1:dvbsYZD+MHkdIZl+Z67D212hEvB+GII2tfH8f9SnoDw=
+charm.land/fantasy v0.17.2 h1:ojTMufMxY/PVH7TzYUxht2SVkvD90iCTJfmPR6c8BR8=
+charm.land/fantasy v0.17.2/go.mod h1:V9cCIUMZB9g3Bq40aKEY8xBNzDd48EdfHp2OMS0uzWs=
 charm.land/huh/v2 v2.0.3 h1:2cJsMqEPwSywGHvdlKsJyQKPtSJLVnFKyFbsYZTlLkU=
 charm.land/huh/v2 v2.0.3/go.mod h1:93eEveeeqn47MwiC3tf+2atZ2l7Is88rAtmZNZ8x9Wc=
-charm.land/lipgloss/v2 v2.0.2 h1:xFolbF8JdpNkM2cEPTfXEcW1p6NRzOWTSamRfYEw8cs=
-charm.land/lipgloss/v2 v2.0.2/go.mod h1:KjPle2Qd3YmvP1KL5OMHiHysGcNwq6u83MUjYkFvEkM=
+charm.land/lipgloss/v2 v2.0.3 h1:yM2zJ4Cf5Y51b7RHIwioil4ApI/aypFXXVHSwlM6RzU=
+charm.land/lipgloss/v2 v2.0.3/go.mod h1:7myLU9iG/3xluAWzpY/fSxYYHCgoKTie7laxk6ATwXA=
 cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE=
 cloud.google.com/go v0.123.0/go.mod h1:xBoMV08QcqUGuPW65Qfm1o9Y4zKZBpGS+7bImXLTAZU=
-cloud.google.com/go/auth v0.19.0 h1:DGYwtbcsGsT1ywuxsIoWi1u/vlks0moIblQHgSDgQkQ=
-cloud.google.com/go/auth v0.19.0/go.mod h1:2Aph7BT2KnaSFOM0JDPyiYgNh6PL9vGMiP8CUIXZ+IY=
+cloud.google.com/go/auth v0.20.0 h1:kXTssoVb4azsVDoUiF8KvxAqrsQcQtB53DcSgta74CA=
+cloud.google.com/go/auth v0.20.0/go.mod h1:942/yi/itH1SsmpyrbnTMDgGfdy2BUqIKyd0cyYLc5Q=
 cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc=
 cloud.google.com/go/auth/oauth2adapt v0.2.8/go.mod h1:XQ9y31RkqZCcwJWNSx2Xvric3RrU88hAYYbjDWYDL+c=
 cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
 cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
 github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0 h1:fou+2+WFTib47nS+nz/ozhEBnvU96bKHy6LjRsY4E28=
 github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0/go.mod h1:t76Ruy8AHvUAC8GfMWJMa0ElSbuIcO03NLpynfbgsPA=
-github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.10.1 h1:B+blDbyVIG3WaikNxPnhPiJ1MThR03b3vKGtER95TP4=
-github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.10.1/go.mod h1:JdM5psgjfBf5fo2uWOZhflPWyDBZ/O/CNAH9CtsuZE4=
-github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 h1:9iefClla7iYpfYWdzPCRDozdmndjTm8DXdpCzPajMgA=
-github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2/go.mod h1:XtLgD3ZD34DAaVIIAyG3objl5DynM3CQ/vMcbBNJZGI=
-github.com/AzureAD/microsoft-authentication-library-for-go v1.4.2 h1:oygO0locgZJe7PpYPXT5A29ZkwJaPqcva7BVeemZOZs=
-github.com/AzureAD/microsoft-authentication-library-for-go v1.4.2/go.mod h1:wP83P5OoQ5p6ip3ScPr0BAq0BvuPAvacpEuSzyouqAI=
+github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1 h1:Hk5QBxZQC1jb2Fwj6mpzme37xbCDdNTxU7O9eb5+LB4=
+github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1/go.mod h1:IYus9qsFobWIc2YVwe/WPjcnyCkPKtnHAqUYeebc8z0=
+github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0 h1:fhqpLE3UEXi9lPaBRpQ6XuRW0nU7hgg4zlmZZa+a9q4=
+github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0/go.mod h1:7dCRMLwisfRH3dBupKeNCioWYUZ4SS09Z14H+7i8ZoY=
+github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0 h1:XRzhVemXdgvJqCH0sFfrBUTnUJSBrBf7++ypk+twtRs=
+github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0/go.mod h1:HKpQxkWaGLJ+D/5H8QRpyQXA1eKjxkFlOMwck5+33Jk=
 github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
 github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
@@ -38,10 +38,10 @@ github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV
 github.com/aws/aws-sdk-go-v2 v1.41.5/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 h1:eBMB84YGghSocM7PsjmmPffTa+1FBUeNvGvFou6V/4o=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
-github.com/aws/aws-sdk-go-v2/config v1.32.13 h1:5KgbxMaS2coSWRrx9TX/QtWbqzgQkOdEa3sZPhBhCSg=
-github.com/aws/aws-sdk-go-v2/config v1.32.13/go.mod h1:8zz7wedqtCbw5e9Mi2doEwDyEgHcEE9YOJp6a8jdSMY=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.13 h1:mA59E3fokBvyEGHKFdnpNNrvaR351cqiHgRg+JzOSRI=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.13/go.mod h1:yoTXOQKea18nrM69wGF9jBdG4WocSZA1h38A+t/MAsk=
+github.com/aws/aws-sdk-go-v2/config v1.32.14 h1:opVIRo/ZbbI8OIqSOKmpFaY7IwfFUOCCXBsUpJOwDdI=
+github.com/aws/aws-sdk-go-v2/config v1.32.14/go.mod h1:U4/V0uKxh0Tl5sxmCBZ3AecYny4UNlVmObYjKuuaiOo=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.14 h1:n+UcGWAIZHkXzYt87uMFBv/l8THYELoX6gVcUvgl6fI=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.14/go.mod h1:cJKuyWB59Mqi0jM3nFYQRmnHVQIcgoxjEMAbLkpr62w=
 github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21 h1:NUS3K4BTDArQqNu2ih7yeDLaS3bmHD0YndtA6UP884g=
 github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21/go.mod h1:YWNWJQNjKigKY1RHVJCuupeWDrrHjRqHm0N9rdrWzYI=
 github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 h1:Rgg6wvjjtX8bNHcvi9OnXWwcE0a2vGpbwmtICOsvcf4=
@@ -56,14 +56,14 @@ github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3x
 github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21/go.mod h1:r6+pf23ouCB718FUxaqzZdbpYFyDtehyZcmP5KL9FkA=
 github.com/aws/aws-sdk-go-v2/service/signin v1.0.9 h1:QKZH0S178gCmFEgst8hN0mCX1KxLgHBKKY/CLqwP8lg=
 github.com/aws/aws-sdk-go-v2/service/signin v1.0.9/go.mod h1:7yuQJoT+OoH8aqIxw9vwF+8KpvLZ8AWmvmUWHsGQZvI=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.14 h1:GcLE9ba5ehAQma6wlopUesYg/hbcOhFNWTjELkiWkh4=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.14/go.mod h1:WSvS1NLr7JaPunCXqpJnWk1Bjo7IxzZXrZi1QQCkuqM=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.18 h1:mP49nTpfKtpXLt5SLn8Uv8z6W+03jYVoOSAl/c02nog=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.18/go.mod h1:YO8TrYtFdl5w/4vmjL8zaBSsiNp3w0L1FfKVKenZT7w=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.15 h1:lFd1+ZSEYJZYvv9d6kXzhkZu07si3f+GQ1AaYwa2LUM=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.15/go.mod h1:WSvS1NLr7JaPunCXqpJnWk1Bjo7IxzZXrZi1QQCkuqM=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19 h1:dzztQ1YmfPrxdrOiuZRMF6fuOwWlWpD2StNLTceKpys=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19/go.mod h1:YO8TrYtFdl5w/4vmjL8zaBSsiNp3w0L1FfKVKenZT7w=
 github.com/aws/aws-sdk-go-v2/service/sts v1.41.10 h1:p8ogvvLugcR/zLBXTXrTkj0RYBUdErbMnAFFp12Lm/U=
 github.com/aws/aws-sdk-go-v2/service/sts v1.41.10/go.mod h1:60dv0eZJfeVXfbT1tFJinbHrDfSJ2GZl4Q//OSSNAVw=
-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/aws/smithy-go v1.24.3 h1:XgOAaUgx+HhVBoP4v8n6HCQoTRDhoMghKqw4LNHsDNg=
+github.com/aws/smithy-go v1.24.3/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.1 h1:OEIrQ8maEeDBXQDoGCbbTTXYJMYRCRO1fnodZ12Gv5o=
@@ -86,24 +86,26 @@ github.com/charmbracelet/log v1.0.0 h1:HVVVMmfOorfj3BA9i8X8UL69Hoz9lI0PYwXfJvOdR
 github.com/charmbracelet/log v1.0.0/go.mod h1:uYgY3SmLpwJWxmlrPwXvzVYujxis1vAKRV/0VQB7yWA=
 github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266 h1:BW/sZtyd1JyYy0h5adMm3tzpNyL857LWjuTRET6OhpY=
 github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266/go.mod h1:1DahUaExbUZx/jD+FNT2PKP4L9rLE5+ZBRuI8mZjd/E=
-github.com/charmbracelet/ultraviolet v0.0.0-20260330092749-0f94982c930b h1:ASDO9RT6SNKTQN87jO2bRfxHFJq8cgeYdFzivY2gCeM=
-github.com/charmbracelet/ultraviolet v0.0.0-20260330092749-0f94982c930b/go.mod h1:Vo8TffMf0q7Uho/n8e6XpBZvOWtd3g39yX+9P5rRutA=
-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/ultraviolet v0.0.0-20260414011438-8c69ec811b1e h1:O5hZFj55wZQWxMiRtQLa3uLKhZGZGS/j8M3OXinQlrw=
+github.com/charmbracelet/ultraviolet v0.0.0-20260414011438-8c69ec811b1e/go.mod h1:bAAz7dh/FTYfC+oiHavL4mX1tOIBZ0ZwYjSi3qE6ivM=
+github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
+github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
 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/conpty v0.1.1 h1:s1bUxjoi7EpqiXysVtC+a8RrvPPNcNvAjfi4jxsAuEs=
 github.com/charmbracelet/x/conpty v0.1.1/go.mod h1:OmtR77VODEFbiTzGE9G1XiRJAga6011PIm4u5fTNZpk=
+github.com/charmbracelet/x/editor v0.2.0 h1:7XLUKtaRaB8jN7bWU2p2UChiySyaAuIfYiIRg8gGWwk=
+github.com/charmbracelet/x/editor v0.2.0/go.mod h1:p3oQ28TSL3YPd+GKJ1fHWcp+7bVGpedHpXmo0D6t1dY=
 github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86 h1:JSt3B+U9iqk37QUU2Rvb6DSBYRLtWqFqfxf8l5hOZUA=
 github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86/go.mod h1:2P0UgXMEa6TsToMSuFqKFQR+fZTO9CNGUNokkPatT/0=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260330094520-2dce04b6f8a4 h1:pIj18ZCZO4WOVj7jwjLoUb1lC7rS/I8oC3fZWXugNaY=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260330094520-2dce04b6f8a4/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260413165052-6921c759c913 h1:6F/6bu5nBLjodsvaU5xAszTaxtHrDU5UiJarpMPZj48=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260413165052-6921c759c913/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/ordered v0.1.0 h1:55/qLwjIh0gL0Vni+QAWk7T/qRVP6sBf+2agPBgnOFE=
 github.com/charmbracelet/x/exp/ordered v0.1.0/go.mod h1:5UHwmG+is5THxMyCJHNPCn2/ecI07aKNrW+LcResjJ8=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260330094520-2dce04b6f8a4 h1:VSd4zShIAf/4FgEDFJpapEcAPrc7h3dyyN7V9JlJpQw=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260330094520-2dce04b6f8a4/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260413165052-6921c759c913 h1:RiZFY92Ug9iz1CenzxSSQla2Z3WflsR7bIuXq40JlpU=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260413165052-6921c759c913/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
 github.com/charmbracelet/x/exp/strings v0.1.0 h1:i69S2XI7uG1u4NLGeJPSYU++Nmjvpo9nwd6aoEm7gkA=
 github.com/charmbracelet/x/exp/strings v0.1.0/go.mod h1:/ehtMPNh9K4odGFkqYJKpIYyePhdp1hLBRvyY4bWkH8=
 github.com/charmbracelet/x/json v0.2.0 h1:DqB+ZGx2h+Z+1s98HOuOyli+i97wsFQIxP2ZQANTPrQ=
@@ -173,26 +175,26 @@ 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.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.20.0 h1:NIKVuLhDlIV74muWlsMM4CcQZqN6JJ20Qcxd9YMuYcs=
-github.com/googleapis/gax-go/v2 v2.20.0/go.mod h1:But/NJU6TnZsrLai/xBAQLLz+Hc7fHZJt/hsCz3Fih4=
+github.com/googleapis/gax-go/v2 v2.21.0 h1:h45NjjzEO3faG9Lg/cFrBh2PgegVVgzqKzuZl/wMbiI=
+github.com/googleapis/gax-go/v2 v2.21.0/go.mod h1:But/NJU6TnZsrLai/xBAQLLz+Hc7fHZJt/hsCz3Fih4=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
 github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/indaco/herald v0.10.0 h1:XzahEKX6cr50qZQrUdA3QrQBHg8uGm5jETD0UDi21BI=
-github.com/indaco/herald v0.10.0/go.mod h1:T5g1+XLYvpjouhzAGHnAHDCKizhESkoV6+QPZ3DhgWA=
-github.com/indaco/herald-md v0.1.0 h1:zmYudYo+uamzKTBcIffJVJYrqk9xDNnVrTh+de2zciw=
-github.com/indaco/herald-md v0.1.0/go.mod h1:Z1HxPCbSn+/+TFzOM/UbsmKeEk/28NNI6JOTileKXto=
-github.com/kaptinlin/go-i18n v0.3.0 h1:wP76dvYg04bvwTb+8NB+CmdZ2kL7lSSCQ9B/kFv7QHo=
-github.com/kaptinlin/go-i18n v0.3.0/go.mod h1:pVcu9qsW5pOIOoZFJXesRYmLos1vMQrby70JPAoWmJU=
+github.com/indaco/herald v0.13.0 h1:+xVG9Fx5NpuWhwku/9IlRL6I009NnX4VUGKvlZHTRxU=
+github.com/indaco/herald v0.13.0/go.mod h1:T5g1+XLYvpjouhzAGHnAHDCKizhESkoV6+QPZ3DhgWA=
+github.com/indaco/herald-md v0.3.0 h1:hN1cKyrexPPM9PeHBsKuaWvIizSi/iYvM9yzRgtdb8M=
+github.com/indaco/herald-md v0.3.0/go.mod h1:RUHVaDSG45ymJjKyxpDwBocLXrZo93FB4OeYMsw9B9s=
+github.com/kaptinlin/go-i18n v0.4.0 h1:i7L3U2yurg+xhokITtJ0k+mjHnXqkoyz8ju5Wb7W8Oc=
+github.com/kaptinlin/go-i18n v0.4.0/go.mod h1:njA6x0+4MWGcLWT0KLrwekhRPmze1Hnstf2+VJFzwpM=
 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.7 h1:41BlQJ9dskH0oE5DSzBUrl/w4JQYIr6N6L0B5GNyDoM=
 github.com/kaptinlin/jsonschema v0.7.7/go.mod h1:rKjWfyySHSxAD7Li2ctYkPlOu960igoKBvZ2ADRtd5Q=
-github.com/kaptinlin/messageformat-go v0.4.19 h1:A5kuuZ1ybXDQ7kD1aoEWGAOemX7hLsMY0yolgSbgpRI=
-github.com/kaptinlin/messageformat-go v0.4.19/go.mod h1:utSDTfiXTxl66OC5RIEuObLH7Ue3YjbA2X86SYMBYWg=
+github.com/kaptinlin/messageformat-go v0.4.20 h1:a0ufTd5liiUubIGeGxpSTnNS8ZSrN4DV01/wGFmfzMs=
+github.com/kaptinlin/messageformat-go v0.4.20/go.mod h1:FqdEPfQLkqVBX7OBRMPgYwUPvKYJohFD9Ok1BMzCfIo=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -201,12 +203,12 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
 github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/mark3labs/mcp-go v0.46.0 h1:8KRibF4wcKejbLsHxCA/QBVUr5fQ9nwz/n8lGqmaALo=
-github.com/mark3labs/mcp-go v0.46.0/go.mod h1:JKTC7R2LLVagkEWK7Kwu7DbmA6iIvnNAod6yrHiQMag=
-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.21 h1:jJKAZiQH+2mIinzCJIaIG9Be1+0NR+5sz/lYEEjdM8w=
-github.com/mattn/go-runewidth v0.0.21/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mark3labs/mcp-go v0.48.0 h1:o+MXuGW/HCeR2ny5LcAcZQn2bo6I2xaZMEHnpRG+dtw=
+github.com/mark3labs/mcp-go v0.48.0/go.mod h1:JKTC7R2LLVagkEWK7Kwu7DbmA6iIvnNAod6yrHiQMag=
+github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
+github.com/mattn/go-isatty v0.0.21/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
+github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
+github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4=
 github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE=
 github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
@@ -272,55 +274,54 @@ github.com/yuin/goldmark v1.8.2 h1:kEGpgqJXdgbkhcOgBxkC0X0PmoPG1ZyoZ117rDVp4zE=
 github.com/yuin/goldmark v1.8.2/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 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.67.0 h1:yI1/OhfEPy7J9eoa6Sj051C7n5dvpj0QX8g4sRchg04=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0/go.mod h1:NoUCKYWK+3ecatC4HjkRktREheMeEtrXoQxrqYFeHSc=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg=
-go.opentelemetry.io/otel v1.42.0 h1:lSQGzTgVR3+sgJDAU/7/ZMjN9Z+vUip7leaqBKy4sho=
-go.opentelemetry.io/otel v1.42.0/go.mod h1:lJNsdRMxCUIWuMlVJWzecSMuNjE7dOYyWlqOXWkdqCc=
-go.opentelemetry.io/otel/metric v1.42.0 h1:2jXG+3oZLNXEPfNmnpxKDeZsFI5o4J+nz6xUlaFdF/4=
-go.opentelemetry.io/otel/metric v1.42.0/go.mod h1:RlUN/7vTU7Ao/diDkEpQpnz3/92J9ko05BIwxYa2SSI=
-go.opentelemetry.io/otel/sdk v1.42.0 h1:LyC8+jqk6UJwdrI/8VydAq/hvkFKNHZVIWuslJXYsDo=
-go.opentelemetry.io/otel/sdk v1.42.0/go.mod h1:rGHCAxd9DAph0joO4W6OPwxjNTYWghRWmkHuGbayMts=
-go.opentelemetry.io/otel/sdk/metric v1.42.0 h1:D/1QR46Clz6ajyZ3G8SgNlTJKBdGp84q9RKCAZ3YGuA=
-go.opentelemetry.io/otel/sdk/metric v1.42.0/go.mod h1:Ua6AAlDKdZ7tdvaQKfSmnFTdHx37+J4ba8MwVCYM5hc=
-go.opentelemetry.io/otel/trace v1.42.0 h1:OUCgIPt+mzOnaUTpOQcBiM/PLQ/Op7oq6g4LenLmOYY=
-go.opentelemetry.io/otel/trace v1.42.0/go.mod h1:f3K9S+IFqnumBkKhRJMeaZeNk9epyhnCmQh/EysQCdc=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.68.0 h1:0Qx7VGBacMm9ZENQ7TnNObTYI4ShC+lHI16seduaxZo=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.68.0/go.mod h1:Sje3i3MjSPKTSPvVWCaL8ugBzJwik3u4smCjUeuupqg=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0 h1:CqXxU8VOmDefoh0+ztfGaymYbhdB/tT3zs79QaZTNGY=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0/go.mod h1:BuhAPThV8PBHBvg8ZzZ/Ok3idOdhWIodywz2xEcRbJo=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
 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.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
-golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
-golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 h1:jiDhWWeC7jfWqR9c/uplMOqJ0sbNlNWv0UkzE0vX1MA=
-golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90/go.mod h1:xE1HEv6b+1SCZ5/uscMRjUBKtIxworgEcEi+/n9NQDQ=
-golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
-golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
+golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
+golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f h1:W3F4c+6OLc6H2lb//N1q4WpJkhzJCK5J6kUi1NTVXfM=
+golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f/go.mod h1:J1xhfL/vlindoeF/aINzNzt2Bket5bjo9sdOYzOsU80=
+golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
+golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
-golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
-golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
-golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
-golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
+golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
+golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
+golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
+golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
-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.273.0 h1:r/Bcv36Xa/te1ugaN1kdJ5LoA5Wj/cL+a4gj6FiPBjQ=
-google.golang.org/api v0.273.0/go.mod h1:JbAt7mF+XVmWu6xNP8/+CTiGH30ofmCmk9nM8d8fHew=
-google.golang.org/genai v1.52.0 h1:ekVIxWHtLUNbt+v0WWi4j3JT4yrHDEbysMcHQcaCQoI=
-google.golang.org/genai v1.52.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
-google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7 h1:XzmzkmB14QhVhgnawEVsOn6OFsnpyxNPRY9QV01dNB0=
-google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:L43LFes82YgSonw6iTXTxXUX1OlULt4AQtkik4ULL/I=
-google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7 h1:41r6JMbpzBMen0R/4TZeeAmGXSJC7DftGINUodzTkPI=
-google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:EIQZ5bFCfRQDV4MhRle7+OgjNtZ6P1PiZBgAKuxXu/Y=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7 h1:ndE4FoJqsIceKP2oYSnUZqhTdYufCYYkqwtFzfrhI7w=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.79.3 h1:sybAEdRIEtvcD68Gx7dmnwjZKlyfuc61Dyo9pGXXkKE=
-google.golang.org/grpc v1.79.3/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/api v0.275.0 h1:vfY5d9vFVJeWEZT65QDd9hbndr7FyZ2+6mIzGAh71NI=
+google.golang.org/api v0.275.0/go.mod h1:Fnag/EWUPIcJXuIkP1pjoTgS5vdxlk3eeemL7Do6bvw=
+google.golang.org/genai v1.54.0 h1:ZQCa70WMTJDI11FdqWCzGvZ5PanpcpfoO6jl/lrSnGU=
+google.golang.org/genai v1.54.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
+google.golang.org/genproto v0.0.0-20260406210006-6f92a3bedf2d h1:N1Ec54vZnIPd7MnxRiYLW+oY4fDR4BOS/LrssdD9+ek=
+google.golang.org/genproto v0.0.0-20260406210006-6f92a3bedf2d/go.mod h1:c2hJ1grtnH0xUiEKGDGkjGNTJ1Hy2LrblyKOHF0sqRM=
+google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d h1:/aDRtSZJjyLQzm75d+a1wOJaqyKBMvIAfeQmoa3ORiI=
+google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d/go.mod h1:etfGUgejTiadZAUaEP14NP97xi1RGeawqkjDARA/UOs=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 h1:RmoJA1ujG+/lRGNfUnOMfhCy5EipVMyvUE+KNbPbTlw=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
+google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
 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

@@ -23,18 +23,6 @@ import (
 // Version is injected at build time; fallback to "dev".
 var Version = "dev"
 
-// thinkingTagOpen and thinkingTagClose are the XML-style tags that some models
-// (Qwen, DeepSeek) wrap reasoning content in. We parse these to extract
-// reasoning/thinking content and send it as ACP thought updates.
-// Also support <think> format used by some models.
-const (
-	thinkingTagOpen    = "<thinking>"
-	thinkingTagClose   = "</thinking>"
-	shortThinkTagOpen  = "<think>"
-	shortThinkTagClose = "</think>"
-)
-
-// Agent implements the acp.Agent interface, delegating to Kit for LLM
 // execution, tool calls, and session management.
 type Agent struct {
 	conn     *acp.AgentSideConnection
@@ -42,10 +30,6 @@ type Agent struct {
 
 	// toolCallCounter provides unique IDs for tool calls within a turn.
 	toolCallCounter atomic.Int64
-
-	// inThinkingTag tracks whether we're currently inside a <thinking> tag
-	// when parsing streaming content from models that wrap reasoning in XML tags.
-	inThinkingTag bool
 }
 
 // NewAgent creates a new ACP agent backed by Kit.
@@ -144,9 +128,6 @@ func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.Promp
 
 	log.Debug("acp: prompt", "session", sessionID, "prompt_len", len(promptText), "files", len(files))
 
-	// Reset thinking tag state for this new prompt turn
-	a.inThinkingTag = false
-
 	// Create a cancellable context for this prompt turn.
 	promptCtx, cancel := context.WithCancel(ctx)
 	sess.setCancel(cancel)
@@ -230,24 +211,8 @@ func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.S
 		var update *acp.SessionUpdate
 		switch ev := e.(type) {
 		case kit.MessageUpdateEvent:
-			// Handle models that wrap reasoning in <thinking> tags (Qwen, DeepSeek)
-			// Parse the chunk and separate reasoning from regular text
-			reasoning, text := a.parseThinkingTags(ev.Chunk)
-
-			// Send reasoning update if we have reasoning content
-			if reasoning != "" {
-				u := acp.UpdateAgentThoughtText(reasoning)
-				_ = a.conn.SessionUpdate(ctx, acp.SessionNotification{
-					SessionId: sessionID,
-					Update:    u,
-				})
-			}
-
-			// Send text update if we have text content
-			if text != "" {
-				u := acp.UpdateAgentMessageText(text)
-				update = &u
-			}
+			u := acp.UpdateAgentMessageText(ev.Chunk)
+			update = &u
 
 		case kit.ReasoningDeltaEvent:
 			u := acp.UpdateAgentThoughtText(ev.Delta)
@@ -430,81 +395,6 @@ func extractPromptContent(blocks []acp.ContentBlock) (string, []kit.LLMFilePart)
 	return strings.Join(textParts, "\n"), files
 }
 
-// parseThinkingTags parses a text chunk for <thinking> or  tags and separates
-// reasoning content from regular text. This handles models (Qwen, DeepSeek)
-// that wrap reasoning in XML-style tags instead of using proper reasoning events.
-// Returns (reasoningContent, textContent).
-func (a *Agent) parseThinkingTags(chunk string) (reasoning string, text string) {
-	// Handle empty chunk
-	if chunk == "" {
-		return "", ""
-	}
-
-	// Determine which tag format to use (long or short)
-	openTag := thinkingTagOpen
-	closeTag := thinkingTagClose
-
-	if strings.Contains(chunk, shortThinkTagOpen) || strings.Contains(chunk, shortThinkTagClose) {
-		openTag = shortThinkTagOpen
-		closeTag = shortThinkTagClose
-	} else if !strings.Contains(chunk, thinkingTagOpen) && !strings.Contains(chunk, thinkingTagClose) && !a.inThinkingTag {
-		// No tags at all and not in thinking mode - return as text
-		return "", chunk
-	}
-
-	// Check for opening tag
-	if strings.Contains(chunk, openTag) {
-		parts := strings.SplitN(chunk, openTag, 2)
-
-		// Content before the opening tag is regular text
-		if !a.inThinkingTag && parts[0] != "" {
-			text = parts[0]
-		}
-
-		a.inThinkingTag = true
-
-		// Content after the opening tag is reasoning
-		if len(parts) > 1 {
-			// Check if the same chunk contains the closing tag
-			if strings.Contains(parts[1], closeTag) {
-				innerParts := strings.SplitN(parts[1], closeTag, 2)
-				reasoning = innerParts[0]
-				a.inThinkingTag = false
-
-				// Content after closing tag is regular text
-				if len(innerParts) > 1 && innerParts[1] != "" {
-					text += innerParts[1]
-				}
-			} else if parts[1] != "" {
-				// No closing tag yet, all remaining content is reasoning
-				reasoning = parts[1]
-			}
-		}
-		return reasoning, text
-	}
-
-	// Check for closing tag
-	if strings.Contains(chunk, closeTag) {
-		parts := strings.SplitN(chunk, closeTag, 2)
-		a.inThinkingTag = false
-
-		// Content before closing tag is reasoning
-		reasoning = parts[0]
-
-		// Content after closing tag is regular text
-		if len(parts) > 1 && parts[1] != "" {
-			text = parts[1]
-		}
-		return reasoning, text
-	}
-
-	// No tags found - content goes to current mode
-	if a.inThinkingTag {
-		return chunk, ""
-	}
-	return "", chunk
-}
-
 // isTextMimeType returns true if the MIME type indicates text content.
 func isTextMimeType(mimeType string) bool {
 	return strings.HasPrefix(mimeType, "text/") ||

internal/agent/agent.go

@@ -25,11 +25,26 @@ type AgentConfig struct {
 	StreamingEnabled bool
 	DebugLogger      tools.DebugLogger
 
+	// AuthHandler handles OAuth authorization for remote MCP servers.
+	// When set, remote transports are configured with OAuth support.
+	// If nil, remote MCP servers that require OAuth will fail to connect.
+	AuthHandler tools.MCPAuthHandler
+
+	// TokenStoreFactory, if non-nil, creates a custom token store for each
+	// remote MCP server's OAuth tokens. When nil, the default file-based
+	// token store is used.
+	TokenStoreFactory tools.TokenStoreFactory
+
 	// CoreTools overrides the default core tool set. If empty, core.AllTools()
 	// is used. This allows SDK users to provide a custom tool set (e.g.
 	// CodingTools or tools with a custom WorkDir).
 	CoreTools []fantasy.AgentTool
 
+	// DisableCoreTools, when true, prevents loading any core tools.
+	// If both DisableCoreTools is true and CoreTools is empty, the agent
+	// will have no tools (useful for simple chat completions).
+	DisableCoreTools bool
+
 	// ToolWrapper is an optional function that wraps the combined tool list
 	// before it is passed to the LLM agent. Used by the extensions system
 	// to intercept tool calls/results.
@@ -38,6 +53,11 @@ type AgentConfig struct {
 	// ExtraTools are additional tools to include alongside core and MCP tools.
 	// Used by extensions to register custom tools.
 	ExtraTools []fantasy.AgentTool
+
+	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
+	// loading (successfully or with error). The callback receives the server
+	// name, tool count, and any error. Called from the background goroutine.
+	OnMCPServerLoaded func(serverName string, toolCount int, err error)
 }
 
 // ToolCallHandler is a function type for handling tool calls as they happen.
@@ -63,6 +83,10 @@ type ToolCallContentHandler func(content string)
 // ReasoningDeltaHandler is a function type for handling streaming reasoning/thinking deltas.
 type ReasoningDeltaHandler func(delta string)
 
+// ReasoningCompleteHandler is a function type for handling reasoning/thinking completion.
+// Called when the last reasoning token has been processed, before text streaming starts.
+type ReasoningCompleteHandler func()
+
 // ToolOutputHandler is a function type for handling streaming tool output chunks.
 // Used by tools like bash to stream output as it arrives rather than waiting
 // for the command to complete. The isStderr flag indicates if the chunk
@@ -70,6 +94,14 @@ type ReasoningDeltaHandler func(delta string)
 // Note: This is an alias for core.ToolOutputCallback to avoid import cycles.
 type ToolOutputHandler = core.ToolOutputCallback
 
+// StepMessagesHandler is a function type for persisting messages after each
+// complete step in a multi-step agent turn. The handler receives the messages
+// produced by the step (typically an assistant message with tool calls followed
+// by a tool-role message with results, or a final assistant message with text).
+// This enables incremental session persistence so that progress is saved as
+// it happens rather than only at the end of the turn.
+type StepMessagesHandler func(stepMessages []fantasy.Message)
+
 // StepUsageHandler is a function type for handling token usage after each
 // complete step in a multi-step agent turn. This enables real-time cost
 // tracking during long-running tool-calling conversations.
@@ -79,6 +111,10 @@ type StepUsageHandler func(inputTokens, outputTokens, cacheReadTokens, cacheCrea
 // Core tools (bash, read, write, edit, grep, find, ls) are registered as direct
 // AgentTool implementations — no MCP layer, no serialization overhead.
 // Additional tools from external MCP servers can be loaded alongside core tools.
+//
+// When MCP servers are configured, tool loading happens in the background so the
+// agent (and UI) can start immediately. The first LLM call automatically waits
+// for MCP tools to finish loading before proceeding.
 type Agent struct {
 	toolManager      *tools.MCPToolManager
 	fantasyAgent     fantasy.Agent
@@ -92,6 +128,24 @@ type Agent struct {
 	coreTools        []fantasy.AgentTool
 	extraTools       []fantasy.AgentTool
 	toolWrapper      func([]fantasy.AgentTool) []fantasy.AgentTool // stored for SetModel rebuild
+
+	// providerOptions and modelConfig are stored for rebuilding the fantasy
+	// agent when MCP tools arrive asynchronously or on SetModel.
+	providerOptions     fantasy.ProviderOptions
+	skipMaxOutputTokens bool
+	modelConfig         *models.ProviderConfig
+
+	// authHandler and tokenStoreFactory are stored from AgentConfig so that
+	// AddMCPServer() can propagate them when creating a new MCPToolManager
+	// at runtime (i.e. when no MCP servers were configured at init time).
+	authHandler       tools.MCPAuthHandler
+	tokenStoreFactory tools.TokenStoreFactory
+
+	// mcpReady is closed when background MCP tool loading completes (success
+	// or failure). nil when no MCP servers are configured.
+	mcpReady chan struct{}
+	// mcpErr holds any error from background MCP loading.
+	mcpErr error
 }
 
 // GenerateWithLoopResult contains the result and conversation history from an agent interaction.
@@ -106,11 +160,19 @@ type GenerateWithLoopResult struct {
 	TotalUsage fantasy.Usage
 	// StopReason is the LLM provider's finish reason for the final response.
 	StopReason string
+	// PersistedMessageCount is the number of new messages (beyond the original
+	// input) that were already persisted incrementally via OnStepMessages during
+	// generation. The caller should skip these when doing post-generation
+	// persistence to avoid duplicates.
+	PersistedMessageCount int
 }
 
 // NewAgent creates a new Agent with core tools and optional MCP tool integration.
 // Core tools (bash, read, write, edit, grep, find, ls) are always registered.
-// External MCP tools are loaded from the config if any MCP servers are configured.
+// If MCP servers are configured, their tools are loaded in the background —
+// the agent returns immediately and is usable with core tools only. The first
+// LLM call (GenerateWithLoop) automatically waits for MCP tools to finish
+// loading and rebuilds the agent with the full tool set.
 func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 	// Create the LLM provider
 	providerResult, err := models.CreateProvider(ctx, agentConfig.ModelConfig)
@@ -120,34 +182,22 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 
 	// Register core tools (direct AgentTool implementations, no MCP overhead).
 	// Use caller-provided tools if set, otherwise default to all core tools.
-	coreTools := agentConfig.CoreTools
-	if len(coreTools) == 0 {
+	// DisableCoreTools allows explicitly having zero tools (for chat-only mode).
+	var coreTools []fantasy.AgentTool
+	if agentConfig.DisableCoreTools && len(agentConfig.CoreTools) == 0 {
+		// Explicitly zero tools - chat-only mode
+		coreTools = nil
+	} else if len(agentConfig.CoreTools) > 0 {
+		// Custom tools provided - use them
+		coreTools = agentConfig.CoreTools
+	} else {
+		// Default: load all core tools
 		coreTools = core.AllTools()
 	}
 
-	// Build the combined tool list: core tools + any external MCP tools
+	// Build the initial tool list: core tools + extension tools (no MCP yet).
 	allTools := make([]fantasy.AgentTool, len(coreTools))
 	copy(allTools, coreTools)
-
-	// Load external MCP tools if configured
-	var toolManager *tools.MCPToolManager
-	if agentConfig.MCPConfig != nil && len(agentConfig.MCPConfig.MCPServers) > 0 {
-		toolManager = tools.NewMCPToolManager()
-		toolManager.SetModel(providerResult.Model)
-
-		if agentConfig.DebugLogger != nil {
-			toolManager.SetDebugLogger(agentConfig.DebugLogger)
-		}
-
-		if err := toolManager.LoadTools(ctx, agentConfig.MCPConfig); err != nil {
-			// MCP tool loading failures are non-fatal; core tools still work
-			fmt.Printf("Warning: Failed to load MCP tools: %v\n", err)
-		} else {
-			mcpTools := toolManager.GetTools()
-			allTools = append(allTools, mcpTools...)
-		}
-	}
-
 	// Append any extra tools provided by extensions.
 	if len(agentConfig.ExtraTools) > 0 {
 		allTools = append(allTools, agentConfig.ExtraTools...)
@@ -159,6 +209,148 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 	}
 
 	// Build agent options
+	agentOpts := buildAgentOptions(agentConfig, providerResult, allTools)
+
+	// Create the agent
+	fantasyAgent := fantasy.NewAgent(providerResult.Model, agentOpts...)
+
+	// Determine provider type from model string
+	providerType := "default"
+	if agentConfig.ModelConfig != nil && agentConfig.ModelConfig.ModelString != "" {
+		if p, _, err := models.ParseModelString(agentConfig.ModelConfig.ModelString); err == nil {
+			providerType = p
+		}
+	}
+
+	a := &Agent{
+		fantasyAgent:        fantasyAgent,
+		model:               providerResult.Model,
+		providerCloser:      providerResult.Closer,
+		maxSteps:            agentConfig.MaxSteps,
+		systemPrompt:        agentConfig.SystemPrompt,
+		loadingMessage:      providerResult.Message,
+		providerType:        providerType,
+		streamingEnabled:    agentConfig.StreamingEnabled,
+		coreTools:           coreTools,
+		extraTools:          agentConfig.ExtraTools,
+		toolWrapper:         agentConfig.ToolWrapper,
+		providerOptions:     providerResult.ProviderOptions,
+		skipMaxOutputTokens: providerResult.SkipMaxOutputTokens,
+		modelConfig:         agentConfig.ModelConfig,
+		authHandler:         agentConfig.AuthHandler,
+		tokenStoreFactory:   agentConfig.TokenStoreFactory,
+	}
+
+	// Start MCP tool loading in the background if servers are configured.
+	// The mcpReady channel is closed when loading completes (success or failure).
+	if agentConfig.MCPConfig != nil && len(agentConfig.MCPConfig.MCPServers) > 0 {
+		toolManager := tools.NewMCPToolManager()
+		if agentConfig.AuthHandler != nil {
+			toolManager.SetAuthHandler(agentConfig.AuthHandler)
+		}
+		if agentConfig.TokenStoreFactory != nil {
+			toolManager.SetTokenStoreFactory(agentConfig.TokenStoreFactory)
+		}
+		if agentConfig.DebugLogger != nil {
+			toolManager.SetDebugLogger(agentConfig.DebugLogger)
+		}
+		// Set per-server loaded callback if provided.
+		if agentConfig.OnMCPServerLoaded != nil {
+			toolManager.SetOnServerLoaded(agentConfig.OnMCPServerLoaded)
+		}
+		a.toolManager = toolManager
+		a.mcpReady = make(chan struct{})
+
+		go func() {
+			defer close(a.mcpReady)
+			if err := toolManager.LoadTools(ctx, agentConfig.MCPConfig); err != nil {
+				a.mcpErr = err
+				fmt.Printf("Warning: Failed to load MCP tools: %v\n", err)
+			}
+		}()
+	}
+
+	return a, nil
+}
+
+// WaitForMCPTools blocks until background MCP tool loading completes.
+// Returns nil if no MCP servers are configured or if loading succeeded.
+// Returns the loading error if all servers failed. Safe to call multiple times.
+func (a *Agent) WaitForMCPTools() error {
+	if a.mcpReady == nil {
+		return nil
+	}
+	<-a.mcpReady
+	return a.mcpErr
+}
+
+// MCPToolsReady returns true if MCP tool loading has completed (or was never
+// started). This is a non-blocking check useful for UI status display.
+func (a *Agent) MCPToolsReady() bool {
+	if a.mcpReady == nil {
+		return true
+	}
+	select {
+	case <-a.mcpReady:
+		return true
+	default:
+		return false
+	}
+}
+
+// ensureMCPTools waits for MCP tools to load and rebuilds the fantasy agent
+// with the full tool set. Called lazily before the first LLM call.
+// This is idempotent — subsequent calls after the first rebuild are no-ops.
+func (a *Agent) ensureMCPTools() {
+	if a.mcpReady == nil {
+		return
+	}
+	<-a.mcpReady
+
+	// If there are MCP tools, rebuild the fantasy agent to include them.
+	if a.toolManager != nil && len(a.toolManager.GetTools()) > 0 {
+		a.rebuildFantasyAgent()
+	}
+
+	// Nil out the channel so future calls are instant no-ops and we
+	// don't rebuild again.
+	a.mcpReady = nil
+}
+
+// rebuildFantasyAgent reconstructs the fantasy agent with the current full
+// tool set (core + MCP + extension tools). Used after MCP tools arrive
+// asynchronously and by SetModel.
+func (a *Agent) rebuildFantasyAgent() {
+	allTools := make([]fantasy.AgentTool, len(a.coreTools))
+	copy(allTools, a.coreTools)
+	if a.toolManager != nil {
+		allTools = append(allTools, mcpToolsToAgentTools(a.toolManager.GetTools(), a.toolManager)...)
+	}
+	if len(a.extraTools) > 0 {
+		allTools = append(allTools, a.extraTools...)
+	}
+	if a.toolWrapper != nil {
+		allTools = a.toolWrapper(allTools)
+	}
+
+	providerResult := &models.ProviderResult{
+		Model:               a.model,
+		ProviderOptions:     a.providerOptions,
+		SkipMaxOutputTokens: a.skipMaxOutputTokens,
+	}
+	agentOpts := buildAgentOptions(&AgentConfig{
+		ModelConfig:  a.modelConfig,
+		SystemPrompt: a.systemPrompt,
+		MaxSteps:     a.maxSteps,
+	}, providerResult, allTools)
+
+	a.fantasyAgent = fantasy.NewAgent(a.model, agentOpts...)
+}
+
+// buildAgentOptions constructs the fantasy.AgentOption slice from config,
+// provider result, and the combined tool list. Shared by NewAgent,
+// rebuildFantasyAgent, and SetModel.
+func buildAgentOptions(agentConfig *AgentConfig, providerResult *models.ProviderResult, allTools []fantasy.AgentTool) []fantasy.AgentOption {
 	var agentOpts []fantasy.AgentOption
 
 	if agentConfig.SystemPrompt != "" {
@@ -196,33 +388,15 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 		if agentConfig.ModelConfig.TopK != nil {
 			agentOpts = append(agentOpts, fantasy.WithTopK(int64(*agentConfig.ModelConfig.TopK)))
 		}
-	}
-
-	// Create the agent
-	fantasyAgent := fantasy.NewAgent(providerResult.Model, agentOpts...)
-
-	// Determine provider type from model string
-	providerType := "default"
-	if agentConfig.ModelConfig != nil && agentConfig.ModelConfig.ModelString != "" {
-		if p, _, err := models.ParseModelString(agentConfig.ModelConfig.ModelString); err == nil {
-			providerType = p
+		if agentConfig.ModelConfig.FrequencyPenalty != nil {
+			agentOpts = append(agentOpts, fantasy.WithFrequencyPenalty(float64(*agentConfig.ModelConfig.FrequencyPenalty)))
+		}
+		if agentConfig.ModelConfig.PresencePenalty != nil {
+			agentOpts = append(agentOpts, fantasy.WithPresencePenalty(float64(*agentConfig.ModelConfig.PresencePenalty)))
 		}
 	}
 
-	return &Agent{
-		toolManager:      toolManager,
-		fantasyAgent:     fantasyAgent,
-		model:            providerResult.Model,
-		providerCloser:   providerResult.Closer,
-		maxSteps:         agentConfig.MaxSteps,
-		systemPrompt:     agentConfig.SystemPrompt,
-		loadingMessage:   providerResult.Message,
-		providerType:     providerType,
-		streamingEnabled: agentConfig.StreamingEnabled,
-		coreTools:        coreTools,
-		extraTools:       agentConfig.ExtraTools,
-		toolWrapper:      agentConfig.ToolWrapper,
-	}, nil
+	return agentOpts
 }
 
 // GenerateWithLoop processes messages with a custom loop that displays tool calls in real-time.
@@ -231,7 +405,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, nil, nil, nil)
+		onResponse, onToolCallContent, nil, nil, nil, nil, nil, nil)
 }
 
 // GenerateWithLoopAndStreaming processes messages using the agent with streaming and callbacks.
@@ -242,10 +416,17 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 	onResponse ResponseHandler, onToolCallContent ToolCallContentHandler,
 	onStreamingResponse StreamingResponseHandler,
 	onReasoningDelta ReasoningDeltaHandler,
+	onReasoningComplete ReasoningCompleteHandler,
 	onToolOutput ToolOutputHandler,
+	onStepMessages StepMessagesHandler,
 	onStepUsage StepUsageHandler,
 ) (*GenerateWithLoopResult, error) {
 
+	// Wait for background MCP tool loading to complete and rebuild the
+	// fantasy agent with the full tool set. This is a no-op when no MCP
+	// servers are configured or tools have already been integrated.
+	a.ensureMCPTools()
+
 	// Inject tool output handler into context for use by core tools (e.g., bash).
 	if onToolOutput != nil {
 		ctx = core.ContextWithToolOutputCallback(ctx, onToolOutput)
@@ -277,6 +458,10 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 		// when it returns an error, but the OnStepFinish callback fires
 		// for every step that completed before the error occurred.
 		var completedStepMessages []fantasy.Message
+		// persistedCount tracks how many new messages (beyond the original
+		// input) were persisted incrementally via onStepMessages, so the
+		// caller can skip them during post-generation persistence.
+		var persistedCount int
 
 		// Use the streaming agent
 		streamCall := fantasy.AgentStreamCall{
@@ -295,6 +480,17 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				return nil
 			},
 
+			// Reasoning/thinking complete callback
+			OnReasoningEnd: func(id string, _ fantasy.ReasoningContent) error {
+				if ctx.Err() != nil {
+					return ctx.Err()
+				}
+				if onReasoningComplete != nil {
+					onReasoningComplete()
+				}
+				return nil
+			},
+
 			// Text streaming callback
 			OnTextDelta: func(id, text string) error {
 				if ctx.Err() != nil {
@@ -351,6 +547,13 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				// persisted even if a later step is cancelled.
 				completedStepMessages = append(completedStepMessages, step.Messages...)
 
+				// Persist step messages incrementally so progress is saved
+				// as it happens rather than only at the end of the turn.
+				if onStepMessages != nil && len(step.Messages) > 0 {
+					onStepMessages(step.Messages)
+					persistedCount += len(step.Messages)
+				}
+
 				if ctx.Err() != nil {
 					return ctx.Err()
 				}
@@ -381,7 +584,7 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				opts fantasy.PrepareStepFunctionOptions,
 			) (context.Context, fantasy.PrepareStepResult, error) {
 				// Drain all pending steer messages (non-blocking).
-				var steered []string
+				var steered []SteerMessage
 				for {
 					select {
 					case msg := <-steerCh:
@@ -398,9 +601,9 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				if len(steered) > 0 {
 					// Inject each steer message as a user message so the
 					// LLM sees the redirection on the next step.
-					for _, text := range steered {
+					for _, sm := range steered {
 						result.Messages = append(result.Messages,
-							fantasy.NewUserMessage(text))
+							fantasy.NewUserMessage(sm.Text, sm.Files...))
 					}
 					// Notify that steer messages were consumed.
 					if onConsumed != nil {
@@ -429,19 +632,25 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				partialMessages = append(partialMessages, messages...)
 				partialMessages = append(partialMessages, completedStepMessages...)
 				return &GenerateWithLoopResult{
-					ConversationMessages: partialMessages,
+					ConversationMessages:  partialMessages,
+					PersistedMessageCount: persistedCount,
 				}, err
 			}
 			return nil, err
 		}
 
-		// Fire the response callback for callers that use it (e.g. non-streaming
-		// callers that still want the final response notification).
-		if onResponse != nil && result.Response.Content.Text() != "" {
+		// Fire the response callback so callers (e.g. the TUI) can reset
+		// streaming state. This must fire even when the response text is
+		// empty (e.g. reasoning-only responses) so the UI properly resets
+		// the stream component and avoids duplicate content on the next
+		// flush.
+		if onResponse != nil {
 			onResponse(result.Response.Content.Text())
 		}
 
-		return convertAgentResult(result, messages), nil
+		r := convertAgentResult(result, messages)
+		r.PersistedMessageCount = persistedCount
+		return r, nil
 	}
 
 	// Non-streaming path with no callbacks — use the simpler Generate call.
@@ -454,8 +663,9 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 		return nil, err
 	}
 
-	// For non-streaming, fire the response callback with the final text
-	if onResponse != nil && result.Response.Content.Text() != "" {
+	// For non-streaming, fire the response callback so callers can reset
+	// streaming state (see streaming path comment above).
+	if onResponse != nil {
 		onResponse(result.Response.Content.Text())
 	}
 
@@ -597,7 +807,7 @@ func (a *Agent) GetTools() []fantasy.AgentTool {
 	allTools := make([]fantasy.AgentTool, len(a.coreTools))
 	copy(allTools, a.coreTools)
 	if a.toolManager != nil {
-		allTools = append(allTools, a.toolManager.GetTools()...)
+		allTools = append(allTools, mcpToolsToAgentTools(a.toolManager.GetTools(), a.toolManager)...)
 	}
 	if len(a.extraTools) > 0 {
 		allTools = append(allTools, a.extraTools...)
@@ -623,6 +833,72 @@ func (a *Agent) GetExtensionToolCount() int {
 	return len(a.extraTools)
 }
 
+// SetExtraTools replaces the agent's extra tools (e.g. extension-registered
+// tools) and rebuilds the internal agent with the updated tool list. The
+// model, system prompt, and all other configuration are preserved.
+func (a *Agent) SetExtraTools(extraTools []fantasy.AgentTool) {
+	a.extraTools = extraTools
+	a.rebuildFantasyAgent()
+}
+
+// AddMCPServer connects to a new MCP server at runtime and makes its tools
+// available to the agent. Returns the number of tools loaded.
+// If the agent has no tool manager (no MCP servers were configured at init),
+// one is created automatically.
+func (a *Agent) AddMCPServer(ctx context.Context, name string, cfg config.MCPServerConfig) (int, error) {
+	// Ensure MCP tools from initial load are settled first.
+	a.ensureMCPTools()
+
+	if a.toolManager == nil {
+		a.toolManager = tools.NewMCPToolManager()
+		if a.authHandler != nil {
+			a.toolManager.SetAuthHandler(a.authHandler)
+		}
+		if a.tokenStoreFactory != nil {
+			a.toolManager.SetTokenStoreFactory(a.tokenStoreFactory)
+		}
+		a.toolManager.SetOnToolsChanged(func() {
+			a.rebuildFantasyAgent()
+		})
+	}
+
+	count, err := a.toolManager.AddServer(ctx, name, cfg)
+	if err != nil {
+		return 0, err
+	}
+
+	// AddServer's onToolsChanged callback triggers rebuildFantasyAgent,
+	// but only if it was wired. Ensure rebuild happens regardless.
+	a.rebuildFantasyAgent()
+	return count, nil
+}
+
+// RemoveMCPServer disconnects an MCP server and removes its tools from the agent.
+func (a *Agent) RemoveMCPServer(name string) error {
+	if a.toolManager == nil {
+		return fmt.Errorf("no MCP servers loaded")
+	}
+
+	// Ensure MCP tools from initial load are settled first.
+	a.ensureMCPTools()
+
+	err := a.toolManager.RemoveServer(name)
+	if err != nil {
+		return err
+	}
+
+	// RemoveServer's onToolsChanged callback triggers rebuildFantasyAgent,
+	// but ensure rebuild happens regardless.
+	a.rebuildFantasyAgent()
+	return nil
+}
+
+// GetMCPToolManager returns the underlying MCP tool manager.
+// Returns nil if no MCP servers have been configured.
+func (a *Agent) GetMCPToolManager() *tools.MCPToolManager {
+	return a.toolManager
+}
+
 // GetLoadingMessage returns the loading message from provider creation.
 func (a *Agent) GetLoadingMessage() string {
 	return a.loadingMessage
@@ -636,78 +912,88 @@ func (a *Agent) GetLoadedServerNames() []string {
 	return a.toolManager.GetLoadedServerNames()
 }
 
-// SetModel swaps the agent's LLM provider to a new model. The existing tools,
-// system prompt, and configuration are preserved. The old provider is closed
-// if it has a closer. Returns the previous model string for notification.
+// GetMCPPrompts returns all prompts discovered from connected MCP servers.
+// Returns nil if no MCP servers are configured or no prompts were found.
+func (a *Agent) GetMCPPrompts() []tools.MCPPrompt {
+	if a.toolManager == nil {
+		return nil
+	}
+	return a.toolManager.GetPrompts()
+}
+
+// GetMCPPrompt retrieves and expands a specific prompt from an MCP server.
+// This is a lazy call — the server is contacted each time.
+func (a *Agent) GetMCPPrompt(ctx context.Context, serverName, promptName string, args map[string]string) (*tools.MCPPromptResult, error) {
+	if a.toolManager == nil {
+		return nil, fmt.Errorf("no MCP servers configured")
+	}
+	return a.toolManager.GetPrompt(ctx, serverName, promptName, args)
+}
+
+// GetMCPResources returns all resources discovered from connected MCP servers.
+func (a *Agent) GetMCPResources() []tools.MCPResource {
+	if a.toolManager == nil {
+		return nil
+	}
+	return a.toolManager.GetResources()
+}
+
+// ReadMCPResource reads a specific resource from an MCP server by URI.
+func (a *Agent) ReadMCPResource(ctx context.Context, serverName, uri string) (*tools.MCPResourceContent, error) {
+	if a.toolManager == nil {
+		return nil, fmt.Errorf("no MCP servers configured")
+	}
+	return a.toolManager.ReadResource(ctx, serverName, uri)
+}
+
+// SubscribeMCPResource subscribes to change notifications for a resource.
+func (a *Agent) SubscribeMCPResource(ctx context.Context, serverName, uri string) error {
+	if a.toolManager == nil {
+		return fmt.Errorf("no MCP servers configured")
+	}
+	return a.toolManager.SubscribeResource(ctx, serverName, uri)
+}
+
+// UnsubscribeMCPResource cancels change notifications for a resource.
+func (a *Agent) UnsubscribeMCPResource(ctx context.Context, serverName, uri string) error {
+	if a.toolManager == nil {
+		return fmt.Errorf("no MCP servers configured")
+	}
+	return a.toolManager.UnsubscribeResource(ctx, serverName, uri)
+}
+
+// SetModel swaps the agent's LLM provider to a new model. The existing tools
+// and configuration are preserved. When the new model's ProviderConfig carries
+// a system prompt (from per-model settings), it replaces the agent's stored
+// prompt so the rebuilt fantasy agent uses it. The old provider is closed if
+// it has a closer.
 func (a *Agent) SetModel(ctx context.Context, config *models.ProviderConfig) error {
+	// Ensure MCP tools are loaded before rebuilding (SetModel may be called
+	// before the first LLM call).
+	a.ensureMCPTools()
+
 	providerResult, err := models.CreateProvider(ctx, config)
 	if err != nil {
 		return fmt.Errorf("failed to create model provider: %v", err)
 	}
-
-	// Rebuild tool list (same as NewAgent).
-	allTools := make([]fantasy.AgentTool, len(a.coreTools))
-	copy(allTools, a.coreTools)
-	if a.toolManager != nil {
-		allTools = append(allTools, a.toolManager.GetTools()...)
-	}
-	if len(a.extraTools) > 0 {
-		allTools = append(allTools, a.extraTools...)
-	}
-	if a.toolWrapper != nil {
-		allTools = a.toolWrapper(allTools)
-	}
-
-	// Rebuild agent options.
-	var agentOpts []fantasy.AgentOption
-	if a.systemPrompt != "" {
-		agentOpts = append(agentOpts, fantasy.WithSystemPrompt(a.systemPrompt))
-	}
-	if len(allTools) > 0 {
-		agentOpts = append(agentOpts, fantasy.WithTools(allTools...))
-	}
-	if a.maxSteps > 0 {
-		agentOpts = append(agentOpts, fantasy.WithStopConditions(
-			fantasy.StepCountIs(a.maxSteps),
-		))
-	}
-
-	// 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.
-	// Skip max_output_tokens for providers that don't support it (e.g., Codex OAuth)
-	if config.MaxTokens > 0 && !providerResult.SkipMaxOutputTokens {
-		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.
 	if a.providerCloser != nil {
 		_ = a.providerCloser.Close()
 	}
 
-	// Update model info on MCP tool manager.
-	if a.toolManager != nil {
-		a.toolManager.SetModel(providerResult.Model)
-	}
-
 	// Swap fields.
-	a.fantasyAgent = newFantasyAgent
 	a.model = providerResult.Model
 	a.providerCloser = providerResult.Closer
+	a.providerOptions = providerResult.ProviderOptions
+	a.skipMaxOutputTokens = providerResult.SkipMaxOutputTokens
+	a.modelConfig = config
+
+	// Update system prompt when the config carries one (from per-model
+	// settings or the global config). This allows model-specific system
+	// prompts to take effect on model switch.
+	if config.SystemPrompt != "" {
+		a.systemPrompt = config.SystemPrompt
+	}
 
 	// Update provider type.
 	if config.ModelString != "" {
@@ -716,6 +1002,9 @@ func (a *Agent) SetModel(ctx context.Context, config *models.ProviderConfig) err
 		}
 	}
 
+	// Rebuild the fantasy agent with the new model and current tool set.
+	a.rebuildFantasyAgent()
+
 	return nil
 }
 
@@ -725,7 +1014,13 @@ func (a *Agent) GetModel() fantasy.LanguageModel {
 }
 
 // Close closes the agent and cleans up resources.
+// If MCP tools are still loading in the background, Close waits for them
+// to finish before closing connections to avoid resource leaks.
 func (a *Agent) Close() error {
+	// Wait for background MCP loading to finish before closing connections.
+	if a.mcpReady != nil {
+		<-a.mcpReady
+	}
 	var toolErr error
 	if a.toolManager != nil {
 		toolErr = a.toolManager.Close()

internal/agent/agent_mcp_test.go

@@ -0,0 +1,302 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+
+	"github.com/mark3labs/kit/internal/config"
+)
+
+// mockModel is a minimal LanguageModel that satisfies the interface
+// without making real API calls. Used to test tool management wiring.
+type mockModel struct{}
+
+func (m *mockModel) Generate(_ context.Context, _ fantasy.Call) (*fantasy.Response, error) {
+	return &fantasy.Response{}, nil
+}
+func (m *mockModel) Stream(_ context.Context, _ fantasy.Call) (fantasy.StreamResponse, error) {
+	return nil, nil
+}
+func (m *mockModel) GenerateObject(_ context.Context, _ fantasy.ObjectCall) (*fantasy.ObjectResponse, error) {
+	return &fantasy.ObjectResponse{}, nil
+}
+func (m *mockModel) StreamObject(_ context.Context, _ fantasy.ObjectCall) (fantasy.ObjectStreamResponse, error) {
+	return nil, nil
+}
+func (m *mockModel) Provider() string { return "mock" }
+func (m *mockModel) Model() string    { return "mock-model" }
+
+// testdataDir returns the absolute path to the tools testdata directory.
+func testdataDir(t *testing.T) string {
+	t.Helper()
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("cannot determine test file path")
+	}
+	return filepath.Join(filepath.Dir(file), "..", "tools", "testdata")
+}
+
+// echoServerConfig returns an MCPServerConfig for the test echo MCP server.
+func echoServerConfig(t *testing.T) config.MCPServerConfig {
+	t.Helper()
+	script := filepath.Join(testdataDir(t), "echo_server.py")
+	if _, err := os.Stat(script); err != nil {
+		t.Skipf("echo_server.py not found: %v", err)
+	}
+	return config.MCPServerConfig{
+		Command: []string{"python3", script},
+	}
+}
+
+// mockAuthHandler is a minimal MCPAuthHandler for testing that auth handler
+// propagation works without requiring a real OAuth server.
+type mockAuthHandler struct {
+	redirectURI string
+}
+
+func (h *mockAuthHandler) RedirectURI() string { return h.redirectURI }
+func (h *mockAuthHandler) HandleAuth(_ context.Context, _ string, _ string) (string, error) {
+	return "", nil
+}
+
+// newTestAgent creates a minimal Agent with a mock model and no core tools,
+// suitable for testing MCP server management without an API key.
+func newTestAgent() *Agent {
+	model := &mockModel{}
+	a := &Agent{
+		model:        model,
+		coreTools:    nil,
+		extraTools:   nil,
+		maxSteps:     10,
+		systemPrompt: "test",
+		fantasyAgent: fantasy.NewAgent(model),
+	}
+	return a
+}
+
+func TestAgent_AddMCPServer(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	a := newTestAgent()
+	defer func() { _ = a.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Initially no MCP tools.
+	if a.GetMCPToolCount() != 0 {
+		t.Fatalf("Expected 0 MCP tools initially, got %d", a.GetMCPToolCount())
+	}
+
+	// Add a server.
+	count, err := a.AddMCPServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("AddMCPServer failed: %v", err)
+	}
+	if count != 2 {
+		t.Errorf("Expected 2 tools, got %d", count)
+	}
+
+	// Verify tools are in the agent's tool list.
+	if a.GetMCPToolCount() != 2 {
+		t.Errorf("Expected 2 MCP tools, got %d", a.GetMCPToolCount())
+	}
+
+	allTools := a.GetTools()
+	toolNames := make(map[string]bool)
+	for _, tool := range allTools {
+		toolNames[tool.Info().Name] = true
+	}
+	if !toolNames["echo__echo"] {
+		t.Error("Expected tool 'echo__echo' in agent tools")
+	}
+	if !toolNames["echo__greet"] {
+		t.Error("Expected tool 'echo__greet' in agent tools")
+	}
+
+	// Verify loaded server names.
+	names := a.GetLoadedServerNames()
+	found := false
+	for _, n := range names {
+		if n == "echo" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("Expected 'echo' in loaded server names: %v", names)
+	}
+}
+
+func TestAgent_RemoveMCPServer(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	a := newTestAgent()
+	defer func() { _ = a.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Add then remove.
+	_, err := a.AddMCPServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("AddMCPServer failed: %v", err)
+	}
+
+	err = a.RemoveMCPServer("echo")
+	if err != nil {
+		t.Fatalf("RemoveMCPServer failed: %v", err)
+	}
+
+	// Verify tools removed.
+	if a.GetMCPToolCount() != 0 {
+		t.Errorf("Expected 0 MCP tools after removal, got %d", a.GetMCPToolCount())
+	}
+
+	// Verify agent's tool list has no MCP tools.
+	for _, tool := range a.GetTools() {
+		if strings.Contains(tool.Info().Name, "echo__") {
+			t.Errorf("Found leftover tool after removal: %s", tool.Info().Name)
+		}
+	}
+}
+
+func TestAgent_RemoveMCPServer_NoToolManager(t *testing.T) {
+	a := newTestAgent()
+	defer func() { _ = a.Close() }()
+
+	err := a.RemoveMCPServer("nonexistent")
+	if err == nil {
+		t.Fatal("Expected error when no tool manager exists")
+	}
+	if !strings.Contains(err.Error(), "no MCP servers loaded") {
+		t.Errorf("Expected 'no MCP servers loaded' error, got: %v", err)
+	}
+}
+
+func TestAgent_AddMCPServer_CreatesToolManager(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	a := newTestAgent()
+	defer func() { _ = a.Close() }()
+
+	// Initially no tool manager.
+	if a.GetMCPToolManager() != nil {
+		t.Fatal("Expected nil tool manager initially")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+	_, err := a.AddMCPServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("AddMCPServer failed: %v", err)
+	}
+
+	// Tool manager should now exist.
+	if a.GetMCPToolManager() == nil {
+		t.Fatal("Expected tool manager to be created by AddMCPServer")
+	}
+}
+
+func TestAgent_AddRemoveAdd_MCP(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	a := newTestAgent()
+	defer func() { _ = a.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Add → Remove → Add cycle.
+	_, err := a.AddMCPServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("First add failed: %v", err)
+	}
+
+	err = a.RemoveMCPServer("echo")
+	if err != nil {
+		t.Fatalf("Remove failed: %v", err)
+	}
+
+	count, err := a.AddMCPServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("Re-add failed: %v", err)
+	}
+	if count != 2 {
+		t.Errorf("Expected 2 tools on re-add, got %d", count)
+	}
+	if a.GetMCPToolCount() != 2 {
+		t.Errorf("Expected 2 MCP tools after re-add, got %d", a.GetMCPToolCount())
+	}
+}
+
+// TestAgent_AddMCPServer_InheritsAuthHandler verifies that AddMCPServer()
+// propagates the agent's authHandler and tokenStoreFactory to a newly created
+// MCPToolManager (fix for issue #3).
+func TestAgent_AddMCPServer_InheritsAuthHandler(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	handler := &mockAuthHandler{redirectURI: "http://localhost:9999/oauth/callback"}
+
+	model := &mockModel{}
+	a := &Agent{
+		model:             model,
+		coreTools:         nil,
+		extraTools:        nil,
+		maxSteps:          10,
+		systemPrompt:      "test",
+		fantasyAgent:      fantasy.NewAgent(model),
+		authHandler:       handler,
+		tokenStoreFactory: nil, // nil is fine; we just test authHandler propagation
+	}
+	defer func() { _ = a.Close() }()
+
+	// Initially no tool manager.
+	if a.GetMCPToolManager() != nil {
+		t.Fatal("Expected nil tool manager initially")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+	_, err := a.AddMCPServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("AddMCPServer failed: %v", err)
+	}
+
+	// Tool manager should now exist and have the auth handler set.
+	tm := a.GetMCPToolManager()
+	if tm == nil {
+		t.Fatal("Expected tool manager to be created by AddMCPServer")
+	}
+
+	// Verify the auth handler was propagated by checking the field directly.
+	if tm.GetAuthHandler() == nil {
+		t.Fatal("Expected auth handler to be propagated to tool manager")
+	}
+}

internal/agent/factory.go

@@ -36,13 +36,26 @@ type AgentCreationOptions struct {
 	SpinnerFunc SpinnerFunc // Function to show spinner (provided by caller)
 	// DebugLogger is an optional logger for debugging MCP communications
 	DebugLogger tools.DebugLogger // Optional debug logger
+	// AuthHandler handles OAuth authorization for remote MCP servers
+	AuthHandler tools.MCPAuthHandler
+	// TokenStoreFactory, if non-nil, creates a custom token store for each
+	// remote MCP server's OAuth tokens. When nil, the default file-based
+	// token store is used.
+	TokenStoreFactory tools.TokenStoreFactory
 	// CoreTools overrides the default core tool set. If empty, core.AllTools()
 	// is used.
 	CoreTools []fantasy.AgentTool
+	// DisableCoreTools, when true, prevents loading any core tools.
+	// If both DisableCoreTools is true and CoreTools is empty, the agent
+	// will have no tools (useful for simple chat completions).
+	DisableCoreTools bool
 	// ToolWrapper wraps the combined tool list before agent creation.
 	ToolWrapper func([]fantasy.AgentTool) []fantasy.AgentTool
 	// ExtraTools are additional tools to include (e.g. from extensions).
 	ExtraTools []fantasy.AgentTool
+	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
+	// loading (successfully or with error). Called from the background goroutine.
+	OnMCPServerLoaded func(serverName string, toolCount int, err error)
 }
 
 // CreateAgent creates an agent with optional spinner for Ollama models.
@@ -50,15 +63,19 @@ type AgentCreationOptions struct {
 // Returns the created agent or an error if creation fails.
 func CreateAgent(ctx context.Context, opts *AgentCreationOptions) (*Agent, error) {
 	agentConfig := &AgentConfig{
-		ModelConfig:      opts.ModelConfig,
-		MCPConfig:        opts.MCPConfig,
-		SystemPrompt:     opts.SystemPrompt,
-		MaxSteps:         opts.MaxSteps,
-		StreamingEnabled: opts.StreamingEnabled,
-		DebugLogger:      opts.DebugLogger,
-		CoreTools:        opts.CoreTools,
-		ToolWrapper:      opts.ToolWrapper,
-		ExtraTools:       opts.ExtraTools,
+		ModelConfig:       opts.ModelConfig,
+		MCPConfig:         opts.MCPConfig,
+		SystemPrompt:      opts.SystemPrompt,
+		MaxSteps:          opts.MaxSteps,
+		StreamingEnabled:  opts.StreamingEnabled,
+		DebugLogger:       opts.DebugLogger,
+		AuthHandler:       opts.AuthHandler,
+		TokenStoreFactory: opts.TokenStoreFactory,
+		CoreTools:         opts.CoreTools,
+		DisableCoreTools:  opts.DisableCoreTools,
+		ToolWrapper:       opts.ToolWrapper,
+		ExtraTools:        opts.ExtraTools,
+		OnMCPServerLoaded: opts.OnMCPServerLoaded,
 	}
 
 	var agent *Agent

internal/agent/mcp_adapter.go

@@ -0,0 +1,65 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+
+	"charm.land/fantasy"
+
+	"github.com/mark3labs/kit/internal/tools"
+)
+
+// mcpAgentTool adapts an tools.MCPTool to the fantasy.AgentTool interface.
+// This keeps the fantasy dependency confined to the agent layer — the tools
+// package is a pure MCP client library with no LLM framework dependency.
+type mcpAgentTool struct {
+	tool            tools.MCPTool
+	manager         *tools.MCPToolManager
+	providerOptions fantasy.ProviderOptions
+}
+
+// Info returns the fantasy tool info including name, description, and parameter schema.
+func (t *mcpAgentTool) Info() fantasy.ToolInfo {
+	return fantasy.ToolInfo{
+		Name:        t.tool.Name,
+		Description: t.tool.Description,
+		Parameters:  t.tool.Parameters,
+		Required:    t.tool.Required,
+	}
+}
+
+// Run executes the MCP tool by delegating to the MCPToolManager.
+func (t *mcpAgentTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
+	result, err := t.manager.ExecuteTool(ctx, t.tool.Name, call.Input)
+	if err != nil {
+		return fantasy.ToolResponse{}, fmt.Errorf("mcp tool execution failed: %w", err)
+	}
+
+	if result.IsError {
+		return fantasy.NewTextErrorResponse(result.Content), nil
+	}
+	return fantasy.NewTextResponse(result.Content), nil
+}
+
+// ProviderOptions returns provider-specific options for this tool.
+func (t *mcpAgentTool) ProviderOptions() fantasy.ProviderOptions {
+	return t.providerOptions
+}
+
+// SetProviderOptions sets provider-specific options for this tool.
+func (t *mcpAgentTool) SetProviderOptions(opts fantasy.ProviderOptions) {
+	t.providerOptions = opts
+}
+
+// mcpToolsToAgentTools converts a slice of MCPTool to fantasy.AgentTool
+// implementations that route execution through the MCPToolManager.
+func mcpToolsToAgentTools(mcpTools []tools.MCPTool, manager *tools.MCPToolManager) []fantasy.AgentTool {
+	agentTools := make([]fantasy.AgentTool, len(mcpTools))
+	for i, t := range mcpTools {
+		agentTools[i] = &mcpAgentTool{
+			tool:    t,
+			manager: manager,
+		}
+	}
+	return agentTools
+}

internal/agent/steer.go

@@ -1,6 +1,17 @@
 package agent
 
-import "context"
+import (
+	"context"
+
+	"charm.land/fantasy"
+)
+
+// SteerMessage carries a steering prompt and optional file attachments
+// (e.g. clipboard images) through the steer channel.
+type SteerMessage struct {
+	Text  string
+	Files []fantasy.FilePart
+}
 
 // steerChKey is the context key for the steer channel.
 type steerChKey struct{}
@@ -11,7 +22,7 @@ type steerConsumedKey struct{}
 // ContextWithSteerCh returns a new context with the steer channel attached.
 // The agent's PrepareStep function checks this channel between steps and
 // injects any pending steer messages as user messages before the next LLM call.
-func ContextWithSteerCh(ctx context.Context, ch <-chan string) context.Context {
+func ContextWithSteerCh(ctx context.Context, ch <-chan SteerMessage) context.Context {
 	return context.WithValue(ctx, steerChKey{}, ch)
 }
 
@@ -23,8 +34,8 @@ func ContextWithSteerConsumed(ctx context.Context, fn func(count int)) context.C
 }
 
 // steerChFromContext extracts the steer channel from the context, or nil.
-func steerChFromContext(ctx context.Context) <-chan string {
-	ch, _ := ctx.Value(steerChKey{}).(<-chan string)
+func steerChFromContext(ctx context.Context) <-chan SteerMessage {
+	ch, _ := ctx.Value(steerChKey{}).(<-chan SteerMessage)
 	return ch
 }
 

internal/app/app.go

@@ -162,6 +162,24 @@ func (a *App) CancelCurrentStep() {
 	cancel()
 }
 
+// IsBusy returns true when the agent is currently processing a turn.
+func (a *App) IsBusy() bool {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	return a.busy
+}
+
+// Abort cancels the current agent step (if running) and clears the queue.
+// Unlike InterruptAndSend, no new message is injected — the agent simply
+// stops. Safe to call when idle (no-op).
+func (a *App) Abort() {
+	a.mu.Lock()
+	a.queue = a.queue[:0]
+	cancel := a.cancelStep
+	a.mu.Unlock()
+	cancel()
+}
+
 // QueueLength returns the number of prompts currently waiting in the queue.
 //
 // Satisfies ui.AppController.
@@ -187,6 +205,15 @@ func (a *App) QueueLength() int {
 //
 // Satisfies ui.AppController.
 func (a *App) Steer(prompt string) int {
+	return a.SteerWithFiles(prompt, nil)
+}
+
+// SteerWithFiles injects a steering message with optional file attachments
+// (e.g. pasted images) into the currently running agent turn. Behaves like
+// Steer but includes file parts alongside the text.
+//
+// Satisfies ui.AppController.
+func (a *App) SteerWithFiles(prompt string, files []kit.LLMFilePart) int {
 	a.mu.Lock()
 
 	if a.closed {
@@ -195,8 +222,8 @@ func (a *App) Steer(prompt string) int {
 	}
 
 	if !a.busy {
-		// Not busy — start immediately, same as Run().
-		item := queueItem{Prompt: prompt}
+		// Not busy — start immediately, same as RunWithFiles().
+		item := queueItem{Prompt: prompt, Files: files}
 		a.busy = true
 		a.wg.Add(1)
 		a.mu.Unlock()
@@ -211,7 +238,7 @@ func (a *App) Steer(prompt string) int {
 	// execution, before next LLM call). If PrepareStep doesn't fire
 	// (text-only response), drainQueue will pick it up after the turn.
 	if a.opts.Kit != nil {
-		a.opts.Kit.InjectSteer(prompt)
+		a.opts.Kit.InjectSteerWithFiles(prompt, files)
 	}
 	return 1
 }
@@ -390,6 +417,78 @@ func (a *App) CompactConversation(customInstructions string) error {
 	return nil
 }
 
+// CompactAsync is like CompactConversation but calls onComplete/onError
+// callbacks instead of sending TUI events. Used by the extension API's
+// ctx.Compact() which needs callback-based notification.
+func (a *App) CompactAsync(customInstructions string, onComplete func(), onError func(string)) error {
+	a.mu.Lock()
+	if a.closed {
+		a.mu.Unlock()
+		return fmt.Errorf("app is closed")
+	}
+	if a.busy {
+		a.mu.Unlock()
+		return fmt.Errorf("cannot compact while the agent is working")
+	}
+	if a.opts.Kit == nil {
+		a.mu.Unlock()
+		return fmt.Errorf("SDK instance not available")
+	}
+	a.busy = true
+	a.wg.Add(1)
+	a.mu.Unlock()
+
+	go func() {
+		defer a.wg.Done()
+		defer func() {
+			a.mu.Lock()
+			a.busy = false
+			a.mu.Unlock()
+		}()
+
+		// Subscribe to SDK events for streaming compaction summary to the TUI.
+		sendFn := func(msg tea.Msg) {
+			if a.program != nil {
+				a.program.Send(msg)
+			}
+		}
+		unsub := a.subscribeSDKEvents(sendFn, nil)
+		defer unsub()
+
+		result, err := a.opts.Kit.Compact(a.rootCtx, nil, customInstructions)
+		if err != nil {
+			a.sendEvent(CompactErrorEvent{Err: err})
+			if onError != nil {
+				onError(err.Error())
+			}
+			return
+		}
+		if result == nil {
+			a.sendEvent(CompactErrorEvent{Err: fmt.Errorf("nothing to compact")})
+			if onError != nil {
+				onError("nothing to compact")
+			}
+			return
+		}
+
+		// Sync in-memory store with the compacted session.
+		if a.opts.TreeSession != nil {
+			a.store.Replace(a.opts.TreeSession.GetLLMMessages())
+		}
+
+		a.sendEvent(CompactCompleteEvent{
+			Summary:         result.Summary,
+			OriginalTokens:  result.OriginalTokens,
+			CompactedTokens: result.CompactedTokens,
+			MessagesRemoved: result.MessagesRemoved,
+		})
+		if onComplete != nil {
+			onComplete()
+		}
+	}()
+	return nil
+}
+
 // --------------------------------------------------------------------------
 // Non-interactive execution
 // --------------------------------------------------------------------------
@@ -398,6 +497,12 @@ func (a *App) CompactConversation(customInstructions string) error {
 // response text to stdout. No intermediate events are emitted. Blocks until
 // the step completes or ctx is cancelled.
 func (a *App) RunOnce(ctx context.Context, prompt string) error {
+	return a.RunOnceWithFiles(ctx, prompt, nil)
+}
+
+// RunOnceWithFiles executes a single agent step synchronously with optional
+// multimodal file attachments. Prints the response to stdout and returns.
+func (a *App) RunOnceWithFiles(ctx context.Context, prompt string, files []kit.LLMFilePart) error {
 	stepCtx, cancel := context.WithCancel(ctx)
 	defer cancel()
 
@@ -405,7 +510,7 @@ func (a *App) RunOnce(ctx context.Context, prompt string) error {
 	a.cancelStep = cancel
 	a.mu.Unlock()
 
-	result, err := a.executeStep(stepCtx, prompt, nil, nil)
+	result, err := a.executeStep(stepCtx, prompt, nil, files)
 	if err != nil {
 		return err
 	}
@@ -420,6 +525,12 @@ func (a *App) RunOnce(ctx context.Context, prompt string) error {
 // full TurnResult without printing anything. This is used by --json mode to
 // capture structured output for serialization.
 func (a *App) RunOnceResult(ctx context.Context, prompt string) (*kit.TurnResult, error) {
+	return a.RunOnceResultWithFiles(ctx, prompt, nil)
+}
+
+// RunOnceResultWithFiles executes a single agent step synchronously with
+// optional multimodal file attachments and returns the full TurnResult.
+func (a *App) RunOnceResultWithFiles(ctx context.Context, prompt string, files []kit.LLMFilePart) (*kit.TurnResult, error) {
 	stepCtx, cancel := context.WithCancel(ctx)
 	defer cancel()
 
@@ -427,7 +538,7 @@ func (a *App) RunOnceResult(ctx context.Context, prompt string) (*kit.TurnResult
 	a.cancelStep = cancel
 	a.mu.Unlock()
 
-	return a.executeStep(stepCtx, prompt, nil, nil)
+	return a.executeStep(stepCtx, prompt, nil, files)
 }
 
 // RunOnceWithDisplay executes a single agent step synchronously, sending
@@ -441,6 +552,12 @@ func (a *App) RunOnceResult(ctx context.Context, prompt string) (*kit.TurnResult
 //
 // Blocks until the step completes or ctx is cancelled.
 func (a *App) RunOnceWithDisplay(ctx context.Context, prompt string, eventFn func(tea.Msg)) error {
+	return a.RunOnceWithDisplayAndFiles(ctx, prompt, eventFn, nil)
+}
+
+// RunOnceWithDisplayAndFiles executes a single agent step synchronously with
+// optional multimodal file attachments, sending intermediate display events.
+func (a *App) RunOnceWithDisplayAndFiles(ctx context.Context, prompt string, eventFn func(tea.Msg), files []kit.LLMFilePart) error {
 	stepCtx, cancel := context.WithCancel(ctx)
 	defer cancel()
 
@@ -448,7 +565,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, nil)
+	result, err := a.executeStep(stepCtx, prompt, eventFn, files)
 	if err != nil {
 		return err
 	}
@@ -530,8 +647,8 @@ func (a *App) drainQueue(first queueItem) {
 			if leftover := a.opts.Kit.DrainSteer(); len(leftover) > 0 {
 				a.mu.Lock()
 				steerItems := make([]queueItem, len(leftover))
-				for i, text := range leftover {
-					steerItems[i] = queueItem{Prompt: text}
+				for i, sm := range leftover {
+					steerItems[i] = queueItem{Prompt: sm.Text, Files: sm.Files}
 				}
 				a.queue = append(steerItems, a.queue...)
 				a.mu.Unlock()
@@ -788,6 +905,8 @@ func (a *App) subscribeSDKEvents(sendFn func(tea.Msg), stepUsageSeen *atomic.Boo
 			sendFn(StreamChunkEvent{Content: ev.Chunk})
 		case kit.ReasoningDeltaEvent:
 			sendFn(ReasoningChunkEvent{Delta: ev.Delta})
+		case kit.ReasoningCompleteEvent:
+			sendFn(ReasoningCompleteEvent{})
 		case kit.ToolOutputEvent:
 			sendFn(ToolOutputEvent{
 				ToolCallID: ev.ToolCallID,
@@ -829,7 +948,8 @@ func (a *App) QuitFromExtension() {
 // controls styling: "" for plain text, "info" for a system message block,
 // "error" for an error block. In interactive mode it sends an
 // ExtensionPrintEvent through the program so the TUI can render it with the
-// appropriate renderer. In non-interactive mode it falls back to stdout.
+// appropriate renderer. In non-interactive mode it falls back to stderr with
+// a level prefix so errors are distinguishable from plain output.
 func (a *App) PrintFromExtension(level, text string) {
 	a.mu.Lock()
 	prog := a.program
@@ -838,8 +958,16 @@ func (a *App) PrintFromExtension(level, text string) {
 		prog.Send(ExtensionPrintEvent{Text: text, Level: level})
 		return
 	}
-	// Non-interactive fallback: write directly to stdout.
-	fmt.Println(text)
+	// Non-interactive fallback: write to stderr with a level prefix so that
+	// errors and info messages are distinguishable from plain output.
+	switch level {
+	case "error":
+		fmt.Fprintf(os.Stderr, "[ERROR] %s\n", text)
+	case "info":
+		fmt.Fprintf(os.Stderr, "[INFO] %s\n", text)
+	default:
+		fmt.Println(text)
+	}
 }
 
 // SetEditorTextFromExtension sends an EditorTextSetEvent to the TUI to
@@ -896,6 +1024,47 @@ func (a *App) NotifyWidgetUpdate() {
 	}
 }
 
+// NotifyContentReload sends a ContentReloadEvent to the TUI so it refreshes
+// prompt templates and skills from their provider callbacks. Called by file
+// watchers when .md/.txt files change in prompt or skill directories.
+// In non-interactive mode this is a no-op.
+func (a *App) NotifyContentReload() {
+	a.mu.Lock()
+	prog := a.program
+	a.mu.Unlock()
+	if prog != nil {
+		prog.Send(ContentReloadEvent{})
+	}
+}
+
+// NotifyMCPToolsReady sends an MCPToolsReadyEvent to the TUI so it refreshes
+// tool names and MCP tool count from provider callbacks. Called when background
+// MCP tool loading completes. In non-interactive mode this is a no-op.
+func (a *App) NotifyMCPToolsReady() {
+	a.mu.Lock()
+	prog := a.program
+	a.mu.Unlock()
+	if prog != nil {
+		prog.Send(MCPToolsReadyEvent{})
+	}
+}
+
+// NotifyMCPServerLoaded sends an MCPServerLoadedEvent to the TUI so it can
+// display a system message when a single MCP server finishes loading. Called
+// per server as background MCP tool loading progresses.
+func (a *App) NotifyMCPServerLoaded(serverName string, toolCount int, err error) {
+	a.mu.Lock()
+	prog := a.program
+	a.mu.Unlock()
+	if prog != nil {
+		prog.Send(MCPServerLoadedEvent{
+			ServerName: serverName,
+			ToolCount:  toolCount,
+			Error:      err,
+		})
+	}
+}
+
 // SendEvent sends a tea.Msg to the registered program. Safe to call from
 // any goroutine. No-op when no program is registered.
 //
@@ -980,11 +1149,12 @@ func (a *App) PrintBlockFromExtension(opts extensions.PrintBlockOpts) {
 		})
 		return
 	}
-	// Non-interactive fallback.
+	// Non-interactive fallback: render a simple framed block to stderr so
+	// it is visually distinct from plain stdout output.
 	if opts.Subtitle != "" {
-		fmt.Printf("%s\n  — %s\n", opts.Text, opts.Subtitle)
+		fmt.Fprintf(os.Stderr, "--- %s ---\n%s\n", opts.Subtitle, opts.Text)
 	} else {
-		fmt.Println(opts.Text)
+		fmt.Fprintf(os.Stderr, "---\n%s\n---\n", opts.Text)
 	}
 }
 
@@ -1013,9 +1183,10 @@ func (a *App) recordStepUsage(ev kit.StepUsageEvent, stepUsageSeen *atomic.Bool)
 		int(ev.CacheWriteTokens),
 	)
 	// NOTE: We do NOT call SetContextTokens here. Context fill is set once
-	// at turn completion via updateUsageFromTurnResult using FinalUsage.InputTokens,
-	// which reflects the full accumulated context. Per-step context tokens would
-	// cause the display to jump around during multi-step tool calls.
+	// at turn completion via updateUsageFromTurnResult, which sums all token
+	// categories (Input + CacheRead + CacheCreate + Output) from FinalUsage.
+	// Per-step context tokens would cause the display to jump around during
+	// multi-step tool calls.
 }
 
 // updateUsageFromTurnResult records token usage from an SDK TurnResult into the
@@ -1079,15 +1250,30 @@ func (a *App) updateUsageFromTurnResult(result *kit.TurnResult, userPrompt strin
 	}
 
 	// --- Context window fill (drives the % bar) ---
-	// Use FinalUsage.InputTokens as the context window fill. The API's InputTokens
-	// already includes the full conversation history (system prompt + all previous
-	// messages + current user message). Adding OutputTokens would double-count since
-	// the output becomes part of the input for the next turn.
-	if result.FinalUsage != nil && result.FinalUsage.InputTokens > 0 {
-		if a.opts.Debug {
-			log.Printf("[DEBUG] updateUsageFromTurnResult: calling SetContextTokens=%d (FinalUsage.InputTokens)",
-				result.FinalUsage.InputTokens)
+	// Calculate context fill from the LAST API call's usage. The context
+	// window is filled by everything sent to and received from the model:
+	//
+	//   InputTokens       — non-cached input (may be small with prompt caching)
+	//   CacheReadTokens   — input tokens served from cache
+	//   CacheCreationTokens — input tokens written to cache this call
+	//   OutputTokens      — assistant output (becomes input next turn)
+	//
+	// With Anthropic prompt caching, InputTokens can drop to near-zero while
+	// CacheReadTokens holds the bulk of the context. We must sum all four to
+	// get the true context window utilization.
+	//
+	// We use FinalUsage (last step only), NOT TotalUsage, because TotalUsage
+	// sums across all tool-calling steps — and each step re-sends the full
+	// conversation, so TotalUsage massively overstates the actual window fill.
+	if result.FinalUsage != nil {
+		u := result.FinalUsage
+		contextFill := int(u.InputTokens) + int(u.CacheReadTokens) + int(u.CacheCreationTokens) + int(u.OutputTokens)
+		if contextFill > 0 {
+			if a.opts.Debug {
+				log.Printf("[DEBUG] updateUsageFromTurnResult: SetContextTokens=%d (Input=%d + CacheRead=%d + CacheCreate=%d + Output=%d)",
+					contextFill, u.InputTokens, u.CacheReadTokens, u.CacheCreationTokens, u.OutputTokens)
+			}
+			a.opts.UsageTracker.SetContextTokens(contextFill)
 		}
-		a.opts.UsageTracker.SetContextTokens(int(result.FinalUsage.InputTokens))
 	}
 }

internal/app/app_test.go

@@ -630,10 +630,12 @@ func TestUpdateUsageFromTurnResult_recordsWhenInputTokensZero(t *testing.T) {
 	}
 }
 
-// TestUpdateUsageFromTurnResult_contextTokensUsesInputOnly verifies that context
-// window fill uses InputTokens only (not input+output). The API's InputTokens
-// already includes the full conversation history; adding output would double-count.
-func TestUpdateUsageFromTurnResult_contextTokensUsesInputOnly(t *testing.T) {
+// TestUpdateUsageFromTurnResult_contextTokensUsesAllCategories verifies that
+// context window fill uses all token categories from the final API call:
+// InputTokens + CacheReadTokens + CacheCreationTokens + OutputTokens.
+// With Anthropic prompt caching, InputTokens can be near-zero while
+// CacheReadTokens holds the bulk of the context.
+func TestUpdateUsageFromTurnResult_contextTokensUsesAllCategories(t *testing.T) {
 	usage := &usageUpdaterStub{}
 	app := New(Options{UsageTracker: usage}, nil)
 	defer app.Close()
@@ -641,22 +643,26 @@ func TestUpdateUsageFromTurnResult_contextTokensUsesInputOnly(t *testing.T) {
 	app.updateUsageFromTurnResult(&kit.TurnResult{
 		Response: "ok",
 		TotalUsage: &kit.LLMUsage{
-			InputTokens:  1000,
-			OutputTokens: 200,
+			InputTokens:         3,
+			OutputTokens:        5,
+			CacheReadTokens:     0,
+			CacheCreationTokens: 4317,
 		},
 		FinalUsage: &kit.LLMUsage{
-			InputTokens:  1000, // Full context including history
-			OutputTokens: 200,
+			InputTokens:         3,    // Non-cached input (small with caching)
+			OutputTokens:        5,    // Assistant output
+			CacheReadTokens:     0,    // No cache reads on first call
+			CacheCreationTokens: 4317, // System prompt + tools written to cache
 		},
 	}, "prompt", false)
 
 	usage.mu.Lock()
 	defer usage.mu.Unlock()
 
-	// Context tokens should be InputTokens only (1000), not input+output (1200)
-	// because InputTokens already includes the full conversation history
-	if usage.contextCalls != 1 || usage.lastContextTokens != 1000 {
-		t.Fatalf("expected context tokens=1000 (InputTokens only), got calls=%d tokens=%d",
-			usage.contextCalls, usage.lastContextTokens)
+	// Context tokens should be Input + CacheRead + CacheCreate + Output = 4325
+	expected := 3 + 0 + 4317 + 5
+	if usage.contextCalls != 1 || usage.lastContextTokens != expected {
+		t.Fatalf("expected context tokens=%d (all categories), got calls=%d tokens=%d",
+			expected, usage.contextCalls, usage.lastContextTokens)
 	}
 }

internal/app/events.go

@@ -16,6 +16,11 @@ type ReasoningChunkEvent struct {
 	Delta string
 }
 
+// ReasoningCompleteEvent is sent when reasoning/thinking is finished, after
+// the last reasoning token has been processed. The TUI uses this to freeze
+// the reasoning duration counter.
+type ReasoningCompleteEvent struct{}
+
 // ToolCallStartedEvent is sent when a tool call has been parsed and is about to execute.
 // It carries the tool name and its arguments for display purposes.
 type ToolCallStartedEvent struct {
@@ -162,6 +167,25 @@ type ModelChangedEvent struct {
 // from its WidgetProvider on the next render cycle.
 type WidgetUpdateEvent struct{}
 
+// ContentReloadEvent is sent when prompt templates or skills are reloaded
+// from disk (e.g. by a file watcher detecting changes). The TUI refreshes
+// its autocomplete entries and internal state from the provider callbacks.
+type ContentReloadEvent struct{}
+
+// MCPToolsReadyEvent is sent when background MCP tool loading completes.
+// The TUI refreshes its tool names and MCP tool count from provider callbacks
+// so that /tools and the startup info bar reflect the loaded MCP tools.
+type MCPToolsReadyEvent struct{}
+
+// MCPServerLoadedEvent is sent when a single MCP server finishes loading
+// (successfully or with error). The TUI displays a system message so users
+// see real-time progress as each server initializes.
+type MCPServerLoadedEvent struct {
+	ServerName string
+	ToolCount  int
+	Error      error // nil on success
+}
+
 // EditorTextSetEvent is sent when an extension calls ctx.SetEditorText to
 // pre-fill the input editor with text. The TUI handles this by setting the
 // textarea content and moving the cursor to the end.

internal/app/messages_test.go

@@ -3,24 +3,21 @@ package app
 import (
 	"testing"
 
-	"charm.land/fantasy"
-
 	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
-// makeTextMsg builds a minimal kit.LLMMessage using fantasy.NewUserMessage
-// or constructing with the given role.
+// makeTextMsg builds a minimal kit.LLMMessage with the given role and text.
 func makeTextMsg(role, text string) kit.LLMMessage {
 	return kit.LLMMessage{
 		Role:    kit.LLMMessageRole(role),
-		Content: []fantasy.MessagePart{fantasy.TextPart{Text: text}},
+		Content: []kit.LLMMessagePart{kit.LLMTextPart{Text: text}},
 	}
 }
 
 // textOf extracts the plain text from an LLMMessage for assertions.
 func textOf(msg kit.LLMMessage) string {
 	for _, part := range msg.Content {
-		if tp, ok := part.(fantasy.TextPart); ok {
+		if tp, ok := part.(kit.LLMTextPart); ok {
 			return tp.Text
 		}
 	}

internal/app/options.go

@@ -21,8 +21,10 @@ type UsageUpdater interface {
 	// the provider does not return exact counts.
 	EstimateAndUpdateUsage(inputText, outputText string)
 	// SetContextTokens records the approximate current context window fill
-	// level. This should be the final API call's input+output tokens (from
-	// FinalResponse.Usage), NOT the aggregate TotalUsage.
+	// level. This should be the sum of ALL token categories from the last
+	// API call: InputTokens + CacheReadTokens + CacheCreationTokens +
+	// OutputTokens. With Anthropic prompt caching, InputTokens can be
+	// near-zero while CacheReadTokens holds the bulk of the context.
 	SetContextTokens(tokens int)
 }
 

internal/config/config.go

@@ -22,6 +22,20 @@ type MCPServerConfig struct {
 	AllowedTools  []string          `json:"allowedTools,omitempty" yaml:"allowedTools,omitempty"`
 	ExcludedTools []string          `json:"excludedTools,omitempty" yaml:"excludedTools,omitempty"`
 
+	// OAuth configuration for remote servers that don't support dynamic
+	// client registration (e.g. GitHub). When OAuthClientID is set, it is
+	// passed directly to the transport's OAuthConfig instead of relying on
+	// dynamic registration.
+	OAuthClientID     string   `json:"oauthClientId,omitempty" yaml:"oauthClientId,omitempty"`
+	OAuthClientSecret string   `json:"oauthClientSecret,omitempty" yaml:"oauthClientSecret,omitempty"`
+	OAuthScopes       []string `json:"oauthScopes,omitempty" yaml:"oauthScopes,omitempty"`
+
+	// InProcessServer holds a live *server.MCPServer for in-process transport.
+	// When set (and Type is "inprocess"), the connection pool creates an
+	// in-process client instead of spawning a subprocess or making HTTP calls.
+	// This field is never serialized — it is only used programmatically via the SDK.
+	InProcessServer any `json:"-" yaml:"-"`
+
 	// Legacy fields for backward compatibility
 	Transport string         `json:"transport,omitempty"`
 	Args      []string       `json:"args,omitempty"`
@@ -35,13 +49,16 @@ type MCPServerConfig struct {
 func (s *MCPServerConfig) UnmarshalJSON(data []byte) error {
 	// First try to unmarshal as the new format
 	type newFormat struct {
-		Type          string            `json:"type"`
-		Command       []string          `json:"command,omitempty"`
-		Environment   map[string]string `json:"environment,omitempty"`
-		URL           string            `json:"url,omitempty"`
-		Headers       []string          `json:"headers,omitempty"`
-		AllowedTools  []string          `json:"allowedTools,omitempty" yaml:"allowedTools,omitempty"`
-		ExcludedTools []string          `json:"excludedTools,omitempty" yaml:"excludedTools,omitempty"`
+		Type              string            `json:"type"`
+		Command           []string          `json:"command,omitempty"`
+		Environment       map[string]string `json:"environment,omitempty"`
+		URL               string            `json:"url,omitempty"`
+		Headers           []string          `json:"headers,omitempty"`
+		AllowedTools      []string          `json:"allowedTools,omitempty" yaml:"allowedTools,omitempty"`
+		ExcludedTools     []string          `json:"excludedTools,omitempty" yaml:"excludedTools,omitempty"`
+		OAuthClientID     string            `json:"oauthClientId,omitempty" yaml:"oauthClientId,omitempty"`
+		OAuthClientSecret string            `json:"oauthClientSecret,omitempty" yaml:"oauthClientSecret,omitempty"`
+		OAuthScopes       []string          `json:"oauthScopes,omitempty" yaml:"oauthScopes,omitempty"`
 	}
 
 	// Also try legacy format
@@ -66,6 +83,9 @@ func (s *MCPServerConfig) UnmarshalJSON(data []byte) error {
 		s.Headers = newConfig.Headers
 		s.AllowedTools = newConfig.AllowedTools
 		s.ExcludedTools = newConfig.ExcludedTools
+		s.OAuthClientID = newConfig.OAuthClientID
+		s.OAuthClientSecret = newConfig.OAuthClientSecret
+		s.OAuthScopes = newConfig.OAuthScopes
 		return nil
 	}
 
@@ -157,11 +177,28 @@ type Theme struct {
 	Markdown MarkdownThemeConfig `json:"markdown,omitzero" yaml:"markdown,omitempty"`
 }
 
+// GenerationParams defines generation parameter defaults that can be attached
+// to individual models. These act as model-level defaults — CLI flags and
+// global config values take precedence when explicitly set.
+type GenerationParams struct {
+	MaxTokens        *int     `json:"maxTokens,omitempty" yaml:"maxTokens,omitempty"`
+	Temperature      *float32 `json:"temperature,omitempty" yaml:"temperature,omitempty"`
+	TopP             *float32 `json:"topP,omitempty" yaml:"topP,omitempty"`
+	TopK             *int32   `json:"topK,omitempty" yaml:"topK,omitempty"`
+	FrequencyPenalty *float32 `json:"frequencyPenalty,omitempty" yaml:"frequencyPenalty,omitempty"`
+	PresencePenalty  *float32 `json:"presencePenalty,omitempty" yaml:"presencePenalty,omitempty"`
+	StopSequences    []string `json:"stopSequences,omitempty" yaml:"stopSequences,omitempty"`
+	ThinkingLevel    string   `json:"thinkingLevel,omitempty" yaml:"thinkingLevel,omitempty"`
+	SystemPrompt     string   `json:"systemPrompt,omitempty" yaml:"systemPrompt,omitempty"`
+}
+
 // CustomModelConfig defines a custom model that can be used with custom/custom
 // or other custom/ prefixed models. These models are loaded from the config file
 // and merged into the custom provider in the model registry.
 type CustomModelConfig struct {
 	Name        string      `json:"name" yaml:"name"`
+	BaseURL     string      `json:"baseUrl,omitempty" yaml:"baseUrl,omitempty"`
+	APIKey      string      `json:"apiKey,omitempty" yaml:"apiKey,omitempty"`
 	Family      string      `json:"family,omitempty" yaml:"family,omitempty"`
 	Attachment  bool        `json:"attachment,omitempty" yaml:"attachment,omitempty"`
 	Reasoning   bool        `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
@@ -169,6 +206,11 @@ type CustomModelConfig struct {
 	Knowledge   string      `json:"knowledge,omitempty" yaml:"knowledge,omitempty"`
 	Cost        CostConfig  `json:"cost" yaml:"cost"`
 	Limit       LimitConfig `json:"limit" yaml:"limit"`
+
+	// Generation parameter defaults for this model.
+	// These are applied when the user hasn't explicitly set the corresponding
+	// CLI flag or global config value.
+	Params GenerationParams `json:"params,omitzero" yaml:"params,omitempty"`
 }
 
 // CostConfig defines the pricing for a custom model.
@@ -197,11 +239,13 @@ type Config struct {
 	Stream         *bool                      `json:"stream,omitempty" yaml:"stream,omitempty"`
 	Theme          any                        `json:"theme" yaml:"theme"`
 	// Model generation parameters
-	MaxTokens     int      `json:"max-tokens,omitempty" yaml:"max-tokens,omitempty"`
-	Temperature   *float32 `json:"temperature,omitempty" yaml:"temperature,omitempty"`
-	TopP          *float32 `json:"top-p,omitempty" yaml:"top-p,omitempty"`
-	TopK          *int32   `json:"top-k,omitempty" yaml:"top-k,omitempty"`
-	StopSequences []string `json:"stop-sequences,omitempty" yaml:"stop-sequences,omitempty"`
+	MaxTokens        int      `json:"max-tokens,omitempty" yaml:"max-tokens,omitempty"`
+	Temperature      *float32 `json:"temperature,omitempty" yaml:"temperature,omitempty"`
+	TopP             *float32 `json:"top-p,omitempty" yaml:"top-p,omitempty"`
+	TopK             *int32   `json:"top-k,omitempty" yaml:"top-k,omitempty"`
+	FrequencyPenalty *float32 `json:"frequency-penalty,omitempty" yaml:"frequency-penalty,omitempty"`
+	PresencePenalty  *float32 `json:"presence-penalty,omitempty" yaml:"presence-penalty,omitempty"`
+	StopSequences    []string `json:"stop-sequences,omitempty" yaml:"stop-sequences,omitempty"`
 
 	// Thinking / extended reasoning
 	ThinkingLevel string `json:"thinking-level,omitempty" yaml:"thinking-level,omitempty"`
@@ -215,6 +259,12 @@ type Config struct {
 
 	// Custom model definitions (under custom/ provider)
 	CustomModels map[string]CustomModelConfig `json:"customModels,omitempty" yaml:"customModels,omitempty"`
+
+	// Per-model generation parameter overrides. Keys are "provider/model" strings
+	// (e.g. "anthropic/claude-sonnet-4-5-20250929", "openai/gpt-4o"). These
+	// settings act as model-level defaults — CLI flags and global config values
+	// take precedence when explicitly set.
+	ModelSettings map[string]GenerationParams `json:"modelSettings,omitempty" yaml:"modelSettings,omitempty"`
 }
 
 // GetTransportType returns the transport type for the server config, mapping
@@ -233,11 +283,18 @@ func (s *MCPServerConfig) GetTransportType() string {
 			return "stdio"
 		case "remote":
 			return "streamable"
+		case "inprocess":
+			return "inprocess"
 		default:
 			return s.Type
 		}
 	}
 
+	// Programmatic in-process server detection.
+	if s.InProcessServer != nil {
+		return "inprocess"
+	}
+
 	// Backward compatibility: infer transport type
 	if len(s.Command) > 0 {
 		return "stdio"
@@ -268,8 +325,12 @@ func (c *Config) Validate() error {
 			if serverConfig.URL == "" {
 				return fmt.Errorf("server %s: url is required for %s transport", serverName, transport)
 			}
+		case "inprocess":
+			if serverConfig.InProcessServer == nil {
+				return fmt.Errorf("server %s: InProcessServer is required for inprocess transport", serverName)
+			}
 		default:
-			return fmt.Errorf("server %s: unsupported transport type '%s'. Supported types: stdio, sse, streamable", serverName, transport)
+			return fmt.Errorf("server %s: unsupported transport type '%s'. Supported types: stdio, sse, streamable, inprocess", serverName, transport)
 		}
 	}
 	return nil
@@ -363,16 +424,55 @@ mcpServers:
 # debug: false                                 # Enable debug logging
 # system-prompt: "/path/to/system-prompt.txt" # System prompt text file
 
-# Model generation parameters (all optional)
+# Model generation parameters (all optional, apply globally to all models)
 # max-tokens: 4096                             # Maximum tokens in response
 # temperature: 0.7                             # Randomness (0.0-1.0)
 # top-p: 0.95                                  # Nucleus sampling (0.0-1.0)
 # top-k: 40                                    # Top K sampling
+# frequency-penalty: 0.0                        # Penalize frequent tokens (0.0-2.0)
+# presence-penalty: 0.0                         # Penalize present tokens (0.0-2.0)
 # stop-sequences: ["Human:", "Assistant:"]     # Custom stop sequences
 
+# Per-model generation parameter overrides (apply to specific models)
+# These act as model-level defaults — CLI flags and global settings above take precedence.
+# Keys are "provider/model" strings matching the model you use.
+# modelSettings:
+#   anthropic/claude-sonnet-4-5-20250929:
+#     temperature: 0.3
+#     maxTokens: 8192
+#   openai/gpt-4o:
+#     temperature: 0.7
+#     topP: 0.95
+#     topK: 40
+#     frequencyPenalty: 0.1
+#     presencePenalty: 0.1
+#   anthropic/claude-opus-4-6:
+#     thinkingLevel: "high"
+#     maxTokens: 16384
+#     systemPrompt: "You are a deep reasoning assistant."  # or a file path
+
 # API Configuration (can also use environment variables)
 # provider-api-key: "your-api-key"         # API key for OpenAI, Anthropic, or Google
 # provider-url: "https://api.openai.com/v1" # Base URL for OpenAI, Anthropic, or Ollama
+
+# Custom model definitions (under custom/ provider)
+# customModels:
+#   my-local-llama:
+#     name: "Local Llama 3"
+#     baseUrl: "http://localhost:8080/v1"
+#     family: "llama"
+#     temperature: true
+#     cost:
+#       input: 0.0
+#       output: 0.0
+#     limit:
+#       context: 131072
+#       output: 8192
+#     params:                              # Generation parameter defaults for this model
+#       temperature: 0.8
+#       topP: 0.95
+#       topK: 40
+#       systemPrompt: "You are a helpful local assistant."
 `
 
 	_, err = file.WriteString(content)

internal/config/config_test.go

@@ -6,6 +6,8 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"gopkg.in/yaml.v3"
 )
 
 func TestMCPServerConfig_NewFormat(t *testing.T) {
@@ -542,3 +544,86 @@ func TestEnsureConfigExistsWhenFileExists(t *testing.T) {
 		t.Error("Existing config file was modified when it shouldn't have been")
 	}
 }
+
+func TestMCPServerConfig_OAuthFields_JSON(t *testing.T) {
+	jsonData := `{
+		"type": "remote",
+		"url": "https://api.githubcopilot.com/mcp/",
+		"oauthClientId": "Ov23liXXXXXXXXXXXXXX",
+		"oauthClientSecret": "secret123",
+		"oauthScopes": ["read:user", "repo"]
+	}`
+
+	var cfg MCPServerConfig
+	err := json.Unmarshal([]byte(jsonData), &cfg)
+	if err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+
+	if cfg.Type != "remote" {
+		t.Errorf("Expected type 'remote', got %q", cfg.Type)
+	}
+	if cfg.URL != "https://api.githubcopilot.com/mcp/" {
+		t.Errorf("Expected URL, got %q", cfg.URL)
+	}
+	if cfg.OAuthClientID != "Ov23liXXXXXXXXXXXXXX" {
+		t.Errorf("Expected OAuthClientID 'Ov23liXXXXXXXXXXXXXX', got %q", cfg.OAuthClientID)
+	}
+	if cfg.OAuthClientSecret != "secret123" {
+		t.Errorf("Expected OAuthClientSecret 'secret123', got %q", cfg.OAuthClientSecret)
+	}
+	if len(cfg.OAuthScopes) != 2 || cfg.OAuthScopes[0] != "read:user" || cfg.OAuthScopes[1] != "repo" {
+		t.Errorf("Expected OAuthScopes [read:user, repo], got %v", cfg.OAuthScopes)
+	}
+}
+
+func TestMCPServerConfig_OAuthFields_YAML(t *testing.T) {
+	yamlData := `
+type: remote
+url: https://api.githubcopilot.com/mcp/
+oauthClientId: "Ov23liXXXXXXXXXXXXXX"
+oauthScopes:
+  - read:user
+  - repo
+`
+
+	var cfg MCPServerConfig
+	err := yaml.Unmarshal([]byte(yamlData), &cfg)
+	if err != nil {
+		t.Fatalf("Failed to unmarshal YAML: %v", err)
+	}
+
+	if cfg.Type != "remote" {
+		t.Errorf("Expected type 'remote', got %q", cfg.Type)
+	}
+	if cfg.OAuthClientID != "Ov23liXXXXXXXXXXXXXX" {
+		t.Errorf("Expected OAuthClientID 'Ov23liXXXXXXXXXXXXXX', got %q", cfg.OAuthClientID)
+	}
+	if len(cfg.OAuthScopes) != 2 || cfg.OAuthScopes[0] != "read:user" || cfg.OAuthScopes[1] != "repo" {
+		t.Errorf("Expected OAuthScopes [read:user, repo], got %v", cfg.OAuthScopes)
+	}
+}
+
+func TestMCPServerConfig_OAuthFields_Omitted(t *testing.T) {
+	// Verify that omitting OAuth fields still works (backward compat).
+	jsonData := `{
+		"type": "remote",
+		"url": "https://example.com/mcp"
+	}`
+
+	var cfg MCPServerConfig
+	err := json.Unmarshal([]byte(jsonData), &cfg)
+	if err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+
+	if cfg.OAuthClientID != "" {
+		t.Errorf("Expected empty OAuthClientID, got %q", cfg.OAuthClientID)
+	}
+	if cfg.OAuthClientSecret != "" {
+		t.Errorf("Expected empty OAuthClientSecret, got %q", cfg.OAuthClientSecret)
+	}
+	if len(cfg.OAuthScopes) != 0 {
+		t.Errorf("Expected empty OAuthScopes, got %v", cfg.OAuthScopes)
+	}
+}

internal/core/read.go

@@ -67,7 +67,7 @@ func executeRead(ctx context.Context, call fantasy.ToolCall, workDir string) (fa
 	}
 
 	if info.IsDir() {
-		return readDirectory(absPath)
+		return fantasy.NewTextErrorResponse(fmt.Sprintf("'%s' is a directory, not a file. Use the ls tool to list directory contents.", args.Path)), nil
 	}
 
 	content, err := os.ReadFile(absPath)
@@ -116,25 +116,6 @@ func executeRead(ctx context.Context, call fantasy.ToolCall, workDir string) (fa
 	return fantasy.NewTextResponse(tr.Content), nil
 }
 
-func readDirectory(absPath string) (fantasy.ToolResponse, error) {
-	entries, err := os.ReadDir(absPath)
-	if err != nil {
-		return fantasy.NewTextErrorResponse(fmt.Sprintf("failed to read directory: %v", err)), nil
-	}
-
-	var result strings.Builder
-	for _, entry := range entries {
-		name := entry.Name()
-		if entry.IsDir() {
-			name += "/"
-		}
-		result.WriteString(name + "\n")
-	}
-
-	tr := truncateHead(result.String(), 500, defaultMaxBytes)
-	return fantasy.NewTextResponse(tr.Content), nil
-}
-
 // resolvePathWithWorkDir resolves a path to an absolute path relative to the
 // given workDir. If workDir is empty, os.Getwd() is used.
 func resolvePathWithWorkDir(path, workDir string) (string, error) {

internal/core/subagent.go

@@ -130,13 +130,22 @@ func executeSubagent(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolRe
 		), fmt.Errorf("no subagent spawner in context")
 	}
 
-	// Detach from the parent's deadline so the subagent gets its own
-	// independent timeout (applied downstream in Kit.Subagent). The parent
-	// context may carry a tight deadline from the LLM generation loop or
-	// other tool timeouts that would prematurely kill the subagent.
-	// We preserve context values (spawner, etc.) and propagate parent
-	// cancellation (e.g. user hits Ctrl-C) without inheriting the deadline.
-	spawnCtx := detachedWithCancel(ctx)
+	// Build a clean context for the subagent that inherits values (e.g. the
+	// spawner callback) but is completely detached from the parent's
+	// deadline AND cancellation. The subagent gets its own independent
+	// timeout (applied downstream in Kit.Subagent).
+	//
+	// Why full detachment instead of propagating parent cancellation?
+	// The parent context may already be done (deadline exceeded or
+	// cancelled) by the time this tool handler executes — for example when
+	// the generation loop context carries a deadline, when the user
+	// double-ESC cancels mid-turn, or when parallel tool execution
+	// encounters a race between stream completion and tool dispatch. Using
+	// context.WithoutCancel (Go 1.21+) ensures the subagent always starts
+	// cleanly with a fresh timeout, following the pattern used by crush for
+	// shutdown-resilient child work. The subagent's own timeout
+	// (defaultSubagentTimeout / user-specified) provides the safety net.
+	spawnCtx := context.WithoutCancel(valuesContext{parent: ctx})
 
 	// Spawn in-process subagent.
 	result, err := spawner(spawnCtx, call.ID, args.Task, args.Model, args.SystemPrompt, timeout)
@@ -173,37 +182,21 @@ func executeSubagent(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolRe
 }
 
 // ---------------------------------------------------------------------------
-// Context detachment
+// Context helpers
 // ---------------------------------------------------------------------------
 
-// detachedContext wraps a parent context, preserving its values but removing
-// its deadline and cancellation. This allows the subagent to have its own
-// independent timeout while still accessing context-stored values (e.g. the
-// subagent spawner function).
-type detachedContext struct {
+// valuesContext preserves a parent context's values (e.g. the subagent
+// spawner callback) while stripping its deadline and cancellation. Combined
+// with context.WithoutCancel() this gives the subagent a completely clean
+// context that only inherits value-based dependencies.
+type valuesContext struct {
 	parent context.Context
 }
 
-func (d detachedContext) Deadline() (time.Time, bool) { return time.Time{}, false }
-func (d detachedContext) Done() <-chan struct{}       { return nil }
-func (d detachedContext) Err() error                  { return nil }
-func (d detachedContext) Value(key any) any           { return d.parent.Value(key) }
-
-// detachedWithCancel creates a new context that inherits values from the
-// parent but has no deadline. Cancellation of the parent is propagated: when
-// the parent is cancelled the returned context is also cancelled, but the
-// parent's deadline does not apply to the child.
-func detachedWithCancel(parent context.Context) context.Context {
-	child, cancel := context.WithCancel(detachedContext{parent: parent})
-	go func() {
-		select {
-		case <-parent.Done():
-			cancel()
-		case <-child.Done():
-		}
-	}()
-	return child
-}
+func (v valuesContext) Deadline() (time.Time, bool) { return time.Time{}, false }
+func (v valuesContext) Done() <-chan struct{}       { return nil }
+func (v valuesContext) Err() error                  { return nil }
+func (v valuesContext) Value(key any) any           { return v.parent.Value(key) }
 
 // truncateResponse limits the response length to avoid overwhelming context windows.
 func truncateResponse(s string, maxLen int) string {

internal/core/subagent_test.go

@@ -0,0 +1,115 @@
+package core
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestValuesContext_StripsDeadlineAndCancellation(t *testing.T) {
+	// Parent with a tight deadline.
+	parent, cancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
+	defer cancel()
+	time.Sleep(5 * time.Millisecond) // Let deadline expire.
+
+	if parent.Err() == nil {
+		t.Fatal("expected parent to be expired")
+	}
+
+	vc := valuesContext{parent: parent}
+
+	if _, ok := vc.Deadline(); ok {
+		t.Error("valuesContext should report no deadline")
+	}
+	if vc.Done() != nil {
+		t.Error("valuesContext.Done() should return nil")
+	}
+	if vc.Err() != nil {
+		t.Errorf("valuesContext.Err() should be nil, got %v", vc.Err())
+	}
+}
+
+func TestValuesContext_PreservesValues(t *testing.T) {
+	type testKey struct{}
+	parent := context.WithValue(context.Background(), testKey{}, "hello")
+
+	vc := valuesContext{parent: parent}
+
+	got, ok := vc.Value(testKey{}).(string)
+	if !ok || got != "hello" {
+		t.Errorf("expected value 'hello', got %q (ok=%v)", got, ok)
+	}
+}
+
+func TestSpawnContext_SurvivesCancelledParent(t *testing.T) {
+	// Simulate the exact scenario from the bug: the parent generation
+	// context is already cancelled when the subagent tool handler runs.
+	parent, cancel := context.WithCancel(context.Background())
+	cancel() // Cancelled before detach.
+
+	// This is what executeSubagent now does:
+	spawnCtx := context.WithoutCancel(valuesContext{parent: parent})
+
+	// The spawn context must be alive.
+	if spawnCtx.Err() != nil {
+		t.Fatalf("spawnCtx should be alive, got err: %v", spawnCtx.Err())
+	}
+
+	// Adding a timeout should produce a working context.
+	tCtx, tCancel := context.WithTimeout(spawnCtx, 5*time.Second)
+	defer tCancel()
+
+	if tCtx.Err() != nil {
+		t.Fatalf("timeout context should be alive, got err: %v", tCtx.Err())
+	}
+}
+
+func TestSpawnContext_SurvivesDeadlineExceededParent(t *testing.T) {
+	// Simulate: parent had a deadline that already expired.
+	parent, pCancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
+	defer pCancel()
+	time.Sleep(5 * time.Millisecond)
+
+	if parent.Err() != context.DeadlineExceeded {
+		t.Fatalf("expected parent deadline exceeded, got: %v", parent.Err())
+	}
+
+	spawnCtx := context.WithoutCancel(valuesContext{parent: parent})
+
+	if spawnCtx.Err() != nil {
+		t.Fatalf("spawnCtx should be alive after deadline-exceeded parent, got: %v", spawnCtx.Err())
+	}
+}
+
+func TestSpawnContext_PreservesSpawnerValue(t *testing.T) {
+	// Verify the subagent spawner callback survives context detachment.
+	called := false
+	spawner := SubagentSpawnFunc(func(ctx context.Context, toolCallID, prompt, model, systemPrompt string, timeout time.Duration) (*SubagentSpawnResult, error) {
+		called = true
+		return &SubagentSpawnResult{Response: "ok"}, nil
+	})
+
+	parent := WithSubagentSpawner(context.Background(), spawner)
+	// Cancel the parent.
+	parentCtx, cancel := context.WithCancel(parent)
+	cancel()
+
+	spawnCtx := context.WithoutCancel(valuesContext{parent: parentCtx})
+
+	// Should be able to retrieve the spawner from the detached context.
+	recovered := getSubagentSpawner(spawnCtx)
+	if recovered == nil {
+		t.Fatal("spawner should be recoverable from detached context")
+	}
+
+	result, err := recovered(spawnCtx, "tc1", "test task", "", "", time.Minute)
+	if err != nil {
+		t.Fatalf("spawner call failed: %v", err)
+	}
+	if !called {
+		t.Error("spawner was not called")
+	}
+	if result.Response != "ok" {
+		t.Errorf("expected 'ok', got %q", result.Response)
+	}
+}

internal/extensions/api.go

@@ -77,6 +77,64 @@ type Context struct {
 	//   ctx.CancelAndSend("Stop what you're doing and focus on the tests")
 	CancelAndSend func(string)
 
+	// Abort cancels the current agent turn (if running) and clears the
+	// message queue. Unlike CancelAndSend, no new message is injected —
+	// the agent simply stops. Safe to call when idle (no-op).
+	//
+	// Example:
+	//
+	//   ctx.Abort()  // stop whatever the agent is doing
+	Abort func()
+
+	// IsIdle returns true when the agent is not processing a turn.
+	// Extensions can use this to decide whether to dispatch immediately
+	// or queue work for later.
+	//
+	// Example:
+	//
+	//   if ctx.IsIdle() {
+	//       ctx.SendMessage("start new task")
+	//   }
+	IsIdle func() bool
+
+	// Compact triggers context compaction, summarising older messages to
+	// free context window space. Returns an error if compaction cannot
+	// start (e.g. agent is busy or app is closed). The actual compaction
+	// runs asynchronously; use OnComplete/OnError callbacks in
+	// CompactConfig to observe the result.
+	//
+	// Example:
+	//
+	//   err := ctx.Compact(ext.CompactConfig{
+	//       OnComplete: func() { ctx.PrintInfo("Compaction done") },
+	//       OnError:    func(errMsg string) { ctx.PrintError("Compact failed: " + errMsg) },
+	//   })
+	Compact func(CompactConfig) error
+
+	// SendMultimodalMessage injects a message with file attachments (images,
+	// documents) into the conversation and triggers a new agent turn. Files
+	// are described by FilePart structs containing the raw bytes, filename,
+	// and MIME type. If the agent is busy the message is queued.
+	//
+	// Example:
+	//
+	//   data, _ := os.ReadFile("photo.jpg")
+	//   ctx.SendMultimodalMessage("Describe this image", []ext.FilePart{
+	//       {Filename: "photo.jpg", Data: data, MediaType: "image/jpeg"},
+	//   })
+	SendMultimodalMessage func(text string, files []FilePart)
+
+	// GetSessionUsage returns aggregated token usage and cost statistics
+	// for the current session. This includes total input/output tokens,
+	// cache read/write tokens, total cost, and request count.
+	//
+	// Example:
+	//
+	//   usage := ctx.GetSessionUsage()
+	//   fmt.Sprintf("Tokens: ↑%d ↓%d Cost: $%.3f",
+	//       usage.TotalInputTokens, usage.TotalOutputTokens, usage.TotalCost)
+	GetSessionUsage func() SessionUsage
+
 	// SetWidget places or updates a persistent widget in the TUI. Widgets
 	// remain visible across agent turns until explicitly removed. The
 	// widget is identified by WidgetConfig.ID; calling SetWidget with the
@@ -860,7 +918,7 @@ type ExtensionEntry struct {
 type ContextMessage struct {
 	// Index is the position of this message in the original context array
 	// (0-based). When returning messages from a ContextPrepareResult,
-	// messages with Index >= 0 reuse the original fantasy.Message at that
+	// messages with Index >= 0 reuse the original LLM message at that
 	// position (preserving tool calls, reasoning, and other complex parts).
 	// Set Index to -1 for newly injected messages (created from Role + Content).
 	Index int
@@ -937,6 +995,48 @@ type StatusBarEntry struct {
 	Priority int
 }
 
+// CompactConfig configures a programmatic context compaction request.
+type CompactConfig struct {
+	// CustomInstructions is optional text appended to the summary prompt
+	// (e.g. "Focus on the API design decisions"). Empty uses the default.
+	CustomInstructions string
+	// OnComplete is called when compaction finishes successfully.
+	// May be nil if the caller doesn't need notification.
+	OnComplete func()
+	// OnError is called when compaction fails. The argument is the error message.
+	// May be nil if the caller doesn't need notification.
+	OnError func(errMsg string)
+}
+
+// FilePart describes a file attachment for multimodal messages. Extensions
+// use this with SendMultimodalMessage to attach images or documents.
+type FilePart struct {
+	// Filename is the name of the file (e.g. "photo.jpg").
+	Filename string
+	// Data is the raw file content.
+	Data []byte
+	// MediaType is the MIME type (e.g. "image/jpeg", "application/pdf").
+	MediaType string
+}
+
+// SessionUsage contains aggregated token usage and cost statistics for
+// the current session. Extensions use this with GetSessionUsage() to
+// report usage information.
+type SessionUsage struct {
+	// TotalInputTokens is the sum of input tokens across all requests.
+	TotalInputTokens int
+	// TotalOutputTokens is the sum of output tokens across all requests.
+	TotalOutputTokens int
+	// TotalCacheReadTokens is the sum of cache read tokens.
+	TotalCacheReadTokens int
+	// TotalCacheWriteTokens is the sum of cache write tokens.
+	TotalCacheWriteTokens int
+	// TotalCost is the total cost in USD across all requests.
+	TotalCost float64
+	// RequestCount is the number of LLM requests made in this session.
+	RequestCount int
+}
+
 // PrintBlockOpts configures a custom styled block for PrintBlock.
 type PrintBlockOpts struct {
 	// Text is the main content to display.

internal/extensions/installer.go

@@ -154,6 +154,11 @@ func NewInstaller(projectDir string) *Installer {
 
 // Install clones a git repository to the appropriate scope.
 func (i *Installer) Install(source *GitSource, scope InstallScope) error {
+	return i.install(source, scope, nil)
+}
+
+// install is the internal implementation that supports optional include paths.
+func (i *Installer) install(source *GitSource, scope InstallScope, includePaths []string) error {
 	targetDir := i.getInstallPath(source, scope)
 
 	// Check if already installed
@@ -199,6 +204,7 @@ func (i *Installer) Install(source *GitSource, scope InstallScope) error {
 		Pinned:    source.Pinned,
 		Scope:     scope,
 		Installed: time.Now(),
+		Include:   includePaths,
 	}
 	if err := i.addToManifest(entry, scope); err != nil {
 		// Don't fail the install, just log the error
@@ -268,7 +274,22 @@ func (i *Installer) Update(source *GitSource, scope InstallScope) error {
 	cleanCmd.Dir = targetDir
 	_ = cleanCmd.Run() // Ignore errors - clean is best effort
 
-	// Update manifest timestamp
+	// Update manifest timestamp, preserving existing fields like Include
+	existing, _ := i.loadManifest(scope)
+	var include []string
+	var installed time.Time
+	if existing != nil {
+		for _, p := range existing.Packages {
+			if p.Host+"/"+p.Path == source.Identity() {
+				include = p.Include
+				installed = p.Installed
+				break
+			}
+		}
+	}
+	if installed.IsZero() {
+		installed = time.Now()
+	}
 	entry := ManifestEntry{
 		Source:    source.String(),
 		Repo:      source.Repo,
@@ -277,8 +298,9 @@ func (i *Installer) Update(source *GitSource, scope InstallScope) error {
 		Ref:       "",
 		Pinned:    false,
 		Scope:     scope,
-		Installed: time.Now(),
+		Installed: installed,
 		Updated:   time.Now(),
+		Include:   include,
 	}
 	_ = i.addToManifest(entry, scope) // Best effort - don't fail update if manifest fails
 
@@ -503,30 +525,7 @@ func (i *Installer) PreviewExtensions(source *GitSource) ([]ExtensionPreview, st
 // InstallWithInclude clones a repo and installs only the specified extensions.
 // includePaths are relative paths like "./git/main.go" - if empty, installs all.
 func (i *Installer) InstallWithInclude(source *GitSource, scope InstallScope, includePaths []string) error {
-	// First, do a regular install
-	if err := i.Install(source, scope); err != nil {
-		return err
-	}
-
-	// If specific includes were requested, update the manifest
-	if len(includePaths) > 0 {
-		entry := ManifestEntry{
-			Source:  source.String(),
-			Repo:    source.Repo,
-			Host:    source.Host,
-			Path:    source.Path,
-			Ref:     source.Ref,
-			Pinned:  source.Pinned,
-			Scope:   scope,
-			Include: includePaths,
-		}
-
-		if err := addEntryToManifest(entry, scope); err != nil {
-			return fmt.Errorf("updating manifest with includes: %w", err)
-		}
-	}
-
-	return nil
+	return i.install(source, scope, includePaths)
 }
 
 // CleanupTempDir removes a temporary directory used for preview.

internal/extensions/loader.go

@@ -34,15 +34,10 @@ func LoadExtensions(extraPaths []string) ([]LoadedExtension, error) {
 	for _, p := range paths {
 		ext, err := loadSingleExtension(p)
 		if err != nil {
-			log.Warn("skipping extension", "path", p, "err", err)
 			continue
 		}
 		loaded = append(loaded, *ext)
-		log.Debug("loaded extension", "path", p,
-			"handlers", countHandlers(ext),
-			"tools", len(ext.Tools),
-			"commands", len(ext.Commands),
-			"tool_renderers", len(ext.ToolRenderers))
+		log.Debug("loaded extension", "path", p, "handlers", countHandlers(ext), "tools", len(ext.Tools), "commands", len(ext.Commands), "tool_renderers", len(ext.ToolRenderers))
 	}
 	return loaded, nil
 }
@@ -133,7 +128,7 @@ func findExtensionsInDir(dir string) []string {
 
 	for _, entry := range entries {
 		full := filepath.Join(dir, entry.Name())
-		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".go") {
+		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".go") && !strings.HasSuffix(entry.Name(), "_test.go") {
 			results = append(results, full)
 		} else if entry.IsDir() {
 			main := filepath.Join(full, "main.go")
@@ -190,9 +185,13 @@ func findExtensionsInRepo(repoPath string) []string {
 			isExtDir := base == "extensions" || base == "ext" ||
 				strings.HasSuffix(base, "-extensions") || strings.HasSuffix(base, "-ext")
 
-			isExamplesSubdir := relPath == "examples" || strings.HasPrefix(relPath, "examples/")
+			// Allow walking into examples/ so we can reach examples/extensions/ etc,
+			// but don't treat examples/ itself or non-extension subdirs as extension locations.
+			if relPath == "examples" {
+				return nil
+			}
 
-			if !isExtDir && !isExamplesSubdir {
+			if !isExtDir {
 				mainPath := filepath.Join(path, "main.go")
 				if _, err := os.Stat(mainPath); err == nil {
 					if relPath == base { // Top-level directory
@@ -202,13 +201,6 @@ func findExtensionsInRepo(repoPath string) []string {
 						}
 						return filepath.SkipDir
 					}
-					if isExamplesSubdir || isExtDir {
-						if !multiFileDirs[relPath] {
-							multiFileDirs[relPath] = true
-							results = append(results, mainPath)
-						}
-						return filepath.SkipDir
-					}
 				}
 				return filepath.SkipDir
 			}
@@ -227,7 +219,7 @@ func findExtensionsInRepo(repoPath string) []string {
 		}
 
 		// It's a file
-		if !strings.HasSuffix(info.Name(), ".go") {
+		if !strings.HasSuffix(info.Name(), ".go") || strings.HasSuffix(info.Name(), "_test.go") {
 			return nil
 		}
 

internal/extensions/manifest.go

@@ -253,10 +253,13 @@ func ScanForExtensions(dir string) ([]ExtensionPreview, error) {
 			isExtDir := base == "extensions" || base == "ext" ||
 				strings.HasSuffix(base, "-extensions") || strings.HasSuffix(base, "-ext")
 
-			// Or check if it's a subdirectory of examples/ that might contain extensions
-			isExamplesSubdir := relPath == "examples" || strings.HasPrefix(relPath, "examples/")
+			// Allow walking into examples/ so we can reach examples/extensions/ etc,
+			// but don't treat examples/ itself or non-extension subdirs as extension locations.
+			if relPath == "examples" {
+				return nil
+			}
 
-			if !isExtDir && !isExamplesSubdir {
+			if !isExtDir {
 				// Check for main.go before skipping
 				mainPath := filepath.Join(path, "main.go")
 				if _, err := os.Stat(mainPath); err == nil {
@@ -272,18 +275,6 @@ func ScanForExtensions(dir string) ([]ExtensionPreview, error) {
 						}
 						return filepath.SkipDir
 					}
-					// Inside a valid extensions directory
-					if isExamplesSubdir || isExtDir {
-						if !multiFileDirs[relPath] {
-							multiFileDirs[relPath] = true
-							previews = append(previews, ExtensionPreview{
-								Path:   "./" + relPath + "/main.go",
-								Name:   deriveExtensionName(relPath+"/main.go", true),
-								IsMain: true,
-							})
-						}
-						return filepath.SkipDir
-					}
 				}
 
 				// Not an extension location
@@ -309,7 +300,7 @@ func ScanForExtensions(dir string) ([]ExtensionPreview, error) {
 		}
 
 		// It's a file - check if it's a valid extension
-		if !strings.HasSuffix(info.Name(), ".go") {
+		if !strings.HasSuffix(info.Name(), ".go") || strings.HasSuffix(info.Name(), "_test.go") {
 			return nil
 		}
 

internal/extensions/runner.go

@@ -2,12 +2,12 @@ package extensions
 
 import (
 	"fmt"
+	"log"
 	"os"
 	"sort"
 	"strings"
 	"sync"
 
-	"github.com/charmbracelet/log"
 	"github.com/spf13/viper"
 )
 
@@ -86,6 +86,21 @@ func normalizeContext(ctx Context) Context {
 	if ctx.CancelAndSend == nil {
 		ctx.CancelAndSend = func(string) {}
 	}
+	if ctx.Abort == nil {
+		ctx.Abort = func() {}
+	}
+	if ctx.IsIdle == nil {
+		ctx.IsIdle = func() bool { return true }
+	}
+	if ctx.Compact == nil {
+		ctx.Compact = func(CompactConfig) error { return fmt.Errorf("compact not available") }
+	}
+	if ctx.SendMultimodalMessage == nil {
+		ctx.SendMultimodalMessage = func(string, []FilePart) {}
+	}
+	if ctx.GetSessionUsage == nil {
+		ctx.GetSessionUsage = func() SessionUsage { return SessionUsage{} }
+	}
 	if ctx.SetWidget == nil {
 		ctx.SetWidget = func(WidgetConfig) {}
 	}
@@ -355,10 +370,7 @@ func (r *Runner) Emit(event Event) (Result, error) {
 		for _, handler := range handlers {
 			result, err := safeCall(handler, event, ctx)
 			if err != nil {
-				log.Warn("extension handler error",
-					"path", ext.Path,
-					"event", event.Type(),
-					"err", err)
+				log.Printf("WARN extension handler error: path=%s event=%s err=%v", ext.Path, event.Type(), err)
 				continue
 			}
 			if result == nil {
@@ -692,9 +704,7 @@ func (r *Runner) EmitCustomEvent(name, data string) {
 	safeInvoke := func(h func(string)) {
 		defer func() {
 			if rec := recover(); rec != nil {
-				log.Warn("custom event handler panicked",
-					"event", name,
-					"err", fmt.Sprintf("%v", rec))
+				log.Printf("WARN custom event handler panicked: event=%s err=%v", name, rec)
 			}
 		}()
 		h(data)

internal/extensions/symbols.go

@@ -31,6 +31,7 @@ func Symbols() interp.Exports {
 			// Session types
 			"SessionMessage": reflect.ValueOf((*SessionMessage)(nil)),
 			"ExtensionEntry": reflect.ValueOf((*ExtensionEntry)(nil)),
+			"SessionUsage":   reflect.ValueOf((*SessionUsage)(nil)),
 
 			// Option types
 			"OptionDef": reflect.ValueOf((*OptionDef)(nil)),
@@ -44,6 +45,8 @@ func Symbols() interp.Exports {
 			// LLM completion types
 			"CompleteRequest":  reflect.ValueOf((*CompleteRequest)(nil)),
 			"CompleteResponse": reflect.ValueOf((*CompleteResponse)(nil)),
+			"CompactConfig":    reflect.ValueOf((*CompactConfig)(nil)),
+			"FilePart":         reflect.ValueOf((*FilePart)(nil)),
 
 			// Status bar types
 			"StatusBarEntry": reflect.ValueOf((*StatusBarEntry)(nil)),

internal/extensions/watcher.go

@@ -0,0 +1,192 @@
+package extensions
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/fsnotify/fsnotify"
+)
+
+// Watcher monitors extension directories for file changes and triggers
+// a reload callback when .go files are created, modified, or removed.
+// It uses fsnotify for kernel-level file notifications (inotify on Linux,
+// kqueue on macOS) with debouncing to coalesce rapid editor writes.
+type Watcher struct {
+	watcher  *fsnotify.Watcher
+	onReload func()
+	debounce time.Duration
+	cancel   context.CancelFunc
+	done     chan struct{}
+	mu       sync.Mutex
+}
+
+// NewWatcher creates a file watcher that monitors the given directories
+// for .go file changes. When a change is detected (after debouncing),
+// onReload is called. The watcher must be started with Start() and
+// stopped with Close().
+func NewWatcher(dirs []string, onReload func()) (*Watcher, error) {
+	fsw, err := fsnotify.NewWatcher()
+	if err != nil {
+		return nil, fmt.Errorf("creating file watcher: %w", err)
+	}
+
+	for _, dir := range dirs {
+		// Watch the directory itself.
+		if err := fsw.Add(dir); err != nil {
+			log.Printf("DEBUG watcher: skipping directory: dir=%s err=%v", dir, err)
+			continue
+		}
+
+		// Also watch immediate subdirectories (for */main.go pattern).
+		entries, err := os.ReadDir(dir)
+		if err != nil {
+			continue
+		}
+		for _, entry := range entries {
+			if entry.IsDir() {
+				subdir := filepath.Join(dir, entry.Name())
+				if err := fsw.Add(subdir); err != nil {
+					log.Printf("DEBUG watcher: skipping subdirectory: dir=%s err=%v", subdir, err)
+				}
+			}
+		}
+	}
+
+	return &Watcher{
+		watcher:  fsw,
+		onReload: onReload,
+		debounce: 300 * time.Millisecond,
+		done:     make(chan struct{}),
+	}, nil
+}
+
+// Start begins watching for file changes. It blocks until the context
+// is cancelled or Close() is called. Typically called in a goroutine.
+func (w *Watcher) Start(ctx context.Context) {
+	w.mu.Lock()
+	ctx, w.cancel = context.WithCancel(ctx)
+	w.mu.Unlock()
+
+	defer close(w.done)
+
+	var timer *time.Timer
+	var timerC <-chan time.Time
+
+	for {
+		select {
+		case <-ctx.Done():
+			if timer != nil {
+				timer.Stop()
+			}
+			return
+
+		case event, ok := <-w.watcher.Events:
+			if !ok {
+				return
+			}
+
+			// Only care about .go files.
+			if !strings.HasSuffix(event.Name, ".go") {
+				continue
+			}
+
+			// React to write, create, remove, rename events.
+			if event.Op&(fsnotify.Write|fsnotify.Create|fsnotify.Remove|fsnotify.Rename) == 0 {
+				continue
+			}
+
+			log.Printf("DEBUG watcher: file changed: file=%s op=%s", event.Name, event.Op)
+
+			// Debounce: reset timer on each event.
+			if timer != nil {
+				timer.Stop()
+			}
+			timer = time.NewTimer(w.debounce)
+			timerC = timer.C
+
+		case <-timerC:
+			timerC = nil
+			timer = nil
+			log.Printf("DEBUG watcher: reloading extensions")
+			w.onReload()
+
+		case err, ok := <-w.watcher.Errors:
+			if !ok {
+				return
+			}
+			log.Printf("WARN watcher: error: %v", err)
+		}
+	}
+}
+
+// Close stops the watcher and releases resources.
+func (w *Watcher) Close() error {
+	w.mu.Lock()
+	cancel := w.cancel
+	w.mu.Unlock()
+
+	if cancel != nil {
+		cancel()
+	}
+
+	// Wait for the event loop to finish.
+	<-w.done
+	return w.watcher.Close()
+}
+
+// WatchedDirs returns the directories to watch for extension changes.
+// This includes the global extensions directory and the project-local
+// .kit/extensions/ directory (if they exist). Explicit -e paths that
+// point to directories are also included; explicit file paths cause
+// their parent directory to be watched instead.
+func WatchedDirs(extraPaths []string) []string {
+	var dirs []string
+	seen := make(map[string]bool)
+
+	add := func(dir string) {
+		abs, err := filepath.Abs(dir)
+		if err != nil {
+			return
+		}
+		if seen[abs] {
+			return
+		}
+
+		// Verify the directory exists.
+		info, err := os.Stat(abs)
+		if err != nil || !info.IsDir() {
+			return
+		}
+
+		seen[abs] = true
+		dirs = append(dirs, abs)
+	}
+
+	// Global extensions dir.
+	add(globalExtensionsDir())
+
+	// Project-local extensions dir.
+	add(filepath.Join(".kit", "extensions"))
+
+	// Explicit paths that are directories.
+	for _, p := range extraPaths {
+		info, err := os.Stat(p)
+		if err != nil {
+			continue
+		}
+		if info.IsDir() {
+			add(p)
+		} else {
+			// For explicit files, watch the parent directory.
+			add(filepath.Dir(p))
+		}
+	}
+
+	return dirs
+}

internal/extensions/watcher_test.go

@@ -0,0 +1,158 @@
+package extensions
+
+import (
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestWatcher_ReloadsOnGoFileChange(t *testing.T) {
+	dir := t.TempDir()
+
+	// Write an initial extension file.
+	extFile := filepath.Join(dir, "test.go")
+	if err := os.WriteFile(extFile, []byte("package main\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var reloadCount atomic.Int32
+
+	w, err := NewWatcher([]string{dir}, func() {
+		reloadCount.Add(1)
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	go w.Start(t.Context())
+
+	// Modify the file.
+	time.Sleep(50 * time.Millisecond) // let watcher settle
+	if err := os.WriteFile(extFile, []byte("package main\n// changed\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Wait for debounce (300ms) + margin.
+	time.Sleep(600 * time.Millisecond)
+
+	if got := reloadCount.Load(); got != 1 {
+		t.Errorf("expected 1 reload, got %d", got)
+	}
+
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestWatcher_IgnoresNonGoFiles(t *testing.T) {
+	dir := t.TempDir()
+
+	var reloadCount atomic.Int32
+
+	w, err := NewWatcher([]string{dir}, func() {
+		reloadCount.Add(1)
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	go w.Start(t.Context())
+
+	// Write a non-.go file.
+	time.Sleep(50 * time.Millisecond)
+	txtFile := filepath.Join(dir, "notes.txt")
+	if err := os.WriteFile(txtFile, []byte("hello"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Wait past the debounce window.
+	time.Sleep(600 * time.Millisecond)
+
+	if got := reloadCount.Load(); got != 0 {
+		t.Errorf("expected 0 reloads for .txt file, got %d", got)
+	}
+
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestWatcher_Debounces(t *testing.T) {
+	dir := t.TempDir()
+
+	extFile := filepath.Join(dir, "ext.go")
+	if err := os.WriteFile(extFile, []byte("package main\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var reloadCount atomic.Int32
+
+	w, err := NewWatcher([]string{dir}, func() {
+		reloadCount.Add(1)
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	go w.Start(t.Context())
+
+	time.Sleep(50 * time.Millisecond)
+
+	// Rapid-fire writes (simulating editor save: write temp, rename, etc.).
+	for range 5 {
+		if err := os.WriteFile(extFile, []byte("package main\n// changed\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+
+	// Wait for debounce to fire.
+	time.Sleep(600 * time.Millisecond)
+
+	if got := reloadCount.Load(); got != 1 {
+		t.Errorf("expected 1 debounced reload, got %d", got)
+	}
+
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestWatchedDirs_Deduplicates(t *testing.T) {
+	dir := t.TempDir()
+	dirs := WatchedDirs([]string{dir, dir})
+
+	count := 0
+	for _, d := range dirs {
+		abs, _ := filepath.Abs(dir)
+		if d == abs {
+			count++
+		}
+	}
+	if count != 1 {
+		t.Errorf("expected directory to appear once, got %d", count)
+	}
+}
+
+func TestWatchedDirs_FileParent(t *testing.T) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "ext.go")
+	if err := os.WriteFile(file, []byte("package main\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	dirs := WatchedDirs([]string{file})
+
+	abs, _ := filepath.Abs(dir)
+	found := false
+	for _, d := range dirs {
+		if d == abs {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected parent dir %s in watched dirs %v", abs, dirs)
+	}
+}

internal/extensions/wrapper.go

@@ -28,11 +28,11 @@ func WrapToolsWithExtensions(tools []fantasy.AgentTool, runner *Runner) []fantas
 	return wrapped
 }
 
-// ExtensionToolsAsFantasy converts ToolDef values registered by extensions
-// into fantasy.AgentTool implementations so the LLM can invoke them.
+// ExtensionToolsAsLLMTools converts ToolDef values registered by extensions
+// into LLM agent tool implementations so the LLM can invoke them.
 // The runner is optional; if provided, ToolContext.OnProgress routes
 // progress messages through the runner's Print function.
-func ExtensionToolsAsFantasy(defs []ToolDef, runner *Runner) []fantasy.AgentTool {
+func ExtensionToolsAsLLMTools(defs []ToolDef, runner *Runner) []fantasy.AgentTool {
 	tools := make([]fantasy.AgentTool, 0, len(defs))
 	for _, def := range defs {
 		tools = append(tools, &extensionTool{def: def, runner: runner})
@@ -154,7 +154,7 @@ func (w *wrappedTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.T
 }
 
 // ---------------------------------------------------------------------------
-// extensionTool — wraps a ToolDef into a fantasy.AgentTool
+// extensionTool — wraps a ToolDef into an LLM agent tool
 // ---------------------------------------------------------------------------
 
 type extensionTool struct {
@@ -182,7 +182,7 @@ func (t *extensionTool) Info() fantasy.ToolInfo {
 				info.Parameters = props
 			} else {
 				// Schema doesn't have "properties" — use as-is (may be
-				// a flat property map already matching fantasy's format).
+				// a flat property map already matching the expected format).
 				info.Parameters = schema
 			}
 			// Extract required fields if present.

internal/extensions/wrapper_test.go

@@ -192,7 +192,7 @@ func TestWrappedTool_ExecutionStartEnd(t *testing.T) {
 	}
 }
 
-func TestExtensionToolsAsFantasy(t *testing.T) {
+func TestExtensionToolsAsLLMTools(t *testing.T) {
 	defs := []ToolDef{
 		{
 			Name:        "greet",
@@ -202,7 +202,7 @@ func TestExtensionToolsAsFantasy(t *testing.T) {
 		},
 	}
 
-	tools := ExtensionToolsAsFantasy(defs, nil)
+	tools := ExtensionToolsAsLLMTools(defs, nil)
 	if len(tools) != 1 {
 		t.Fatalf("expected 1 tool, got %d", len(tools))
 	}
@@ -232,7 +232,7 @@ func TestExtensionTool_Error(t *testing.T) {
 		},
 	}
 
-	tools := ExtensionToolsAsFantasy(defs, nil)
+	tools := ExtensionToolsAsLLMTools(defs, nil)
 	resp, err := tools[0].Run(context.Background(), fantasy.ToolCall{Input: "x"})
 	if err == nil {
 		t.Error("expected error")
@@ -259,7 +259,7 @@ func TestExtensionTool_ExecuteWithContext(t *testing.T) {
 	}
 
 	// Without runner, OnProgress is a no-op.
-	tools := ExtensionToolsAsFantasy(defs, nil)
+	tools := ExtensionToolsAsLLMTools(defs, nil)
 	resp, err := tools[0].Run(context.Background(), fantasy.ToolCall{Input: "test"})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -285,7 +285,7 @@ func TestExtensionTool_ExecuteWithContext(t *testing.T) {
 			},
 		},
 	}
-	tools2 := ExtensionToolsAsFantasy(defs2, runner)
+	tools2 := ExtensionToolsAsLLMTools(defs2, runner)
 	_, err = tools2[0].Run(context.Background(), fantasy.ToolCall{Input: ""})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -306,7 +306,7 @@ func TestExtensionTool_ExecuteWithContextPriority(t *testing.T) {
 			},
 		},
 	}
-	tools := ExtensionToolsAsFantasy(defs, nil)
+	tools := ExtensionToolsAsLLMTools(defs, nil)
 	resp, err := tools[0].Run(context.Background(), fantasy.ToolCall{Input: ""})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -330,7 +330,7 @@ func TestExtensionTool_CancelledContext(t *testing.T) {
 			},
 		},
 	}
-	tools := ExtensionToolsAsFantasy(defs, nil)
+	tools := ExtensionToolsAsLLMTools(defs, nil)
 	_, _ = tools[0].Run(ctx, fantasy.ToolCall{Input: ""})
 	if !sawCancelled {
 		t.Error("expected IsCancelled=true for cancelled context")
@@ -339,7 +339,7 @@ func TestExtensionTool_CancelledContext(t *testing.T) {
 
 func TestExtensionTool_ProviderOptions(t *testing.T) {
 	defs := []ToolDef{{Name: "test", Execute: func(string) (string, error) { return "", nil }}}
-	tools := ExtensionToolsAsFantasy(defs, nil)
+	tools := ExtensionToolsAsLLMTools(defs, nil)
 
 	// Initially nil.
 	opts := tools[0].ProviderOptions()

internal/fences/fences.go

@@ -0,0 +1,248 @@
+// Package fences provides utilities for detecting markdown code regions
+// (fenced code blocks and inline code spans) and applying transformations
+// only to text outside those regions.
+//
+// This prevents special tokens like $1, $@, or @file from being interpreted
+// when they appear inside ``` fences, ~~~ fences, or `inline` code spans.
+package fences
+
+import "strings"
+
+// Ranges returns byte ranges [start, end) of fenced code blocks in content.
+// Recognises both backtick (```) and tilde (~~~) fences, with optional
+// leading indentation (up to 3 spaces) and optional info strings.
+// An unclosed fence extends to the end of content.
+func Ranges(content string) [][2]int {
+	var result [][2]int
+	var inFence bool
+	var fenceChar byte
+	var fenceCount int
+	var fenceStart int
+
+	pos := 0
+	for pos < len(content) {
+		// Find the end of the current line.
+		lineEnd := strings.IndexByte(content[pos:], '\n')
+		var line string
+		var nextPos int
+		if lineEnd < 0 {
+			line = content[pos:]
+			nextPos = len(content)
+		} else {
+			line = content[pos : pos+lineEnd]
+			nextPos = pos + lineEnd + 1
+		}
+
+		trimmed := strings.TrimLeft(line, " ")
+		indent := len(line) - len(trimmed)
+
+		if !inFence {
+			if indent <= 3 {
+				if ch, n := parseFenceOpen(trimmed); n > 0 {
+					inFence = true
+					fenceChar = ch
+					fenceCount = n
+					fenceStart = pos
+				}
+			}
+		} else {
+			if indent <= 3 && isFenceClose(trimmed, fenceChar, fenceCount) {
+				result = append(result, [2]int{fenceStart, nextPos})
+				inFence = false
+			}
+		}
+
+		pos = nextPos
+	}
+
+	// Unclosed fence extends to end of content.
+	if inFence {
+		result = append(result, [2]int{fenceStart, len(content)})
+	}
+
+	return result
+}
+
+// ReplaceOutside applies fn to each text segment that is outside fenced code
+// blocks and inline code spans, leaving code content unchanged. This is the
+// primary entry point for callers that need to do regex replacement only on
+// non-code text.
+func ReplaceOutside(content string, fn func(string) string) string {
+	ranges := Ranges(content)
+	if len(ranges) == 0 {
+		return replaceOutsideInline(content, fn)
+	}
+
+	var b strings.Builder
+	b.Grow(len(content))
+	pos := 0
+	for _, r := range ranges {
+		if pos < r[0] {
+			// Within non-fenced segments, also skip inline code spans.
+			b.WriteString(replaceOutsideInline(content[pos:r[0]], fn))
+		}
+		// Preserve fenced content verbatim.
+		b.WriteString(content[r[0]:r[1]])
+		pos = r[1]
+	}
+	if pos < len(content) {
+		b.WriteString(replaceOutsideInline(content[pos:], fn))
+	}
+	return b.String()
+}
+
+// StripCode returns content with fenced code blocks and inline code spans
+// removed. Useful for detection/matching where only non-code text matters.
+func StripCode(content string) string {
+	// First strip fenced blocks.
+	stripped := StripFenced(content)
+	// Then strip inline code spans from what remains.
+	return stripInlineCode(stripped)
+}
+
+// StripFenced returns content with fenced code block regions removed.
+// Useful for detection/matching where only non-fenced text matters.
+// NOTE: this does NOT strip inline code spans; use StripCode for both.
+func StripFenced(content string) string {
+	ranges := Ranges(content)
+	if len(ranges) == 0 {
+		return content
+	}
+
+	var b strings.Builder
+	b.Grow(len(content))
+	pos := 0
+	for _, r := range ranges {
+		b.WriteString(content[pos:r[0]])
+		pos = r[1]
+	}
+	b.WriteString(content[pos:])
+	return b.String()
+}
+
+// parseFenceOpen checks whether trimmed (leading spaces already removed)
+// starts a fenced code block. Returns the fence character and count, or
+// (0, 0) if it is not a fence opener.
+func parseFenceOpen(trimmed string) (byte, int) {
+	if len(trimmed) == 0 {
+		return 0, 0
+	}
+	ch := trimmed[0]
+	if ch != '`' && ch != '~' {
+		return 0, 0
+	}
+	count := 0
+	for count < len(trimmed) && trimmed[count] == ch {
+		count++
+	}
+	if count < 3 {
+		return 0, 0
+	}
+	// Per CommonMark: backtick fences cannot have backticks in the info string.
+	if ch == '`' && strings.ContainsRune(trimmed[count:], '`') {
+		return 0, 0
+	}
+	return ch, count
+}
+
+// isFenceClose checks whether trimmed is a closing fence matching fenceChar
+// with at least minCount characters. A closing fence line contains only the
+// fence characters and optional trailing spaces.
+func isFenceClose(trimmed string, fenceChar byte, minCount int) bool {
+	if len(trimmed) == 0 || trimmed[0] != fenceChar {
+		return false
+	}
+	count := 0
+	for count < len(trimmed) && trimmed[count] == fenceChar {
+		count++
+	}
+	if count < minCount {
+		return false
+	}
+	// Closing fence must contain only fence chars (and optional trailing spaces).
+	return strings.TrimRight(trimmed[count:], " ") == ""
+}
+
+// --------------------------------------------------------------------------
+// Inline code span handling
+// --------------------------------------------------------------------------
+
+// inlineCodeRanges returns byte ranges [start, end) of inline code spans
+// in segment. Per CommonMark, a code span opens with N backticks and closes
+// with exactly N backticks.
+func inlineCodeRanges(s string) [][2]int {
+	var result [][2]int
+	i := 0
+	for i < len(s) {
+		if s[i] != '`' {
+			i++
+			continue
+		}
+		// Count opening backticks.
+		start := i
+		n := 0
+		for i < len(s) && s[i] == '`' {
+			n++
+			i++
+		}
+		// Scan for a closing run of exactly n backticks.
+		for j := i; j < len(s); {
+			if s[j] != '`' {
+				j++
+				continue
+			}
+			m := 0
+			for j < len(s) && s[j] == '`' {
+				m++
+				j++
+			}
+			if m == n {
+				result = append(result, [2]int{start, j})
+				i = j
+				break
+			}
+		}
+		// If no closing run was found, i is already past the opening
+		// backticks so the outer loop advances naturally.
+	}
+	return result
+}
+
+// replaceOutsideInline applies fn only to text outside inline code spans.
+func replaceOutsideInline(segment string, fn func(string) string) string {
+	ranges := inlineCodeRanges(segment)
+	if len(ranges) == 0 {
+		return fn(segment)
+	}
+	var b strings.Builder
+	b.Grow(len(segment))
+	pos := 0
+	for _, r := range ranges {
+		if pos < r[0] {
+			b.WriteString(fn(segment[pos:r[0]]))
+		}
+		b.WriteString(segment[r[0]:r[1]])
+		pos = r[1]
+	}
+	if pos < len(segment) {
+		b.WriteString(fn(segment[pos:]))
+	}
+	return b.String()
+}
+
+// stripInlineCode removes inline code spans from s.
+func stripInlineCode(s string) string {
+	ranges := inlineCodeRanges(s)
+	if len(ranges) == 0 {
+		return s
+	}
+	var b strings.Builder
+	b.Grow(len(s))
+	pos := 0
+	for _, r := range ranges {
+		b.WriteString(s[pos:r[0]])
+		pos = r[1]
+	}
+	b.WriteString(s[pos:])
+	return b.String()
+}

internal/fences/fences_test.go

@@ -0,0 +1,313 @@
+package fences
+
+import (
+	"testing"
+)
+
+func TestRanges(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    [][2]int
+	}{
+		{
+			name:    "no fences",
+			content: "hello world\nno code here",
+			want:    nil,
+		},
+		{
+			name:    "single backtick fence",
+			content: "before\n```\ncode\n```\nafter",
+			want:    [][2]int{{7, 20}},
+		},
+		{
+			name:    "single tilde fence",
+			content: "before\n~~~\ncode\n~~~\nafter",
+			want:    [][2]int{{7, 20}},
+		},
+		{
+			name:    "fence with info string",
+			content: "before\n```go\ncode\n```\nafter",
+			want:    [][2]int{{7, 22}},
+		},
+		{
+			name:    "multiple fences",
+			content: "a\n```\nx\n```\nb\n~~~\ny\n~~~\nc",
+			want:    [][2]int{{2, 12}, {14, 24}},
+		},
+		{
+			name:    "unclosed fence",
+			content: "before\n```\ncode\nmore code",
+			want:    [][2]int{{7, 25}},
+		},
+		{
+			name:    "longer closing fence",
+			content: "before\n```\ncode\n`````\nafter",
+			want:    [][2]int{{7, 22}},
+		},
+		{
+			name:    "shorter closing fence ignored",
+			content: "before\n`````\ncode\n```\nmore\n`````\nafter",
+			want:    [][2]int{{7, 33}},
+		},
+		{
+			name:    "indented fence up to 3 spaces",
+			content: "before\n   ```\ncode\n   ```\nafter",
+			want:    [][2]int{{7, 26}},
+		},
+		{
+			name:    "4 space indent is not a fence",
+			content: "before\n    ```\ncode\n    ```\nafter",
+			want:    nil,
+		},
+		{
+			name: "backtick in info string rejects open",
+			// The ```foo`bar line is not a valid opener (backtick in info).
+			// The standalone ``` becomes an opener with no close.
+			content: "before\n```foo`bar\ncode\n```\nafter",
+			want:    [][2]int{{23, 32}},
+		},
+		{
+			name:    "empty content",
+			content: "",
+			want:    nil,
+		},
+		{
+			name:    "fence only",
+			content: "```\ncode\n```",
+			want:    [][2]int{{0, 12}},
+		},
+		{
+			name:    "fence at end without trailing newline",
+			content: "```\ncode\n```",
+			want:    [][2]int{{0, 12}},
+		},
+		{
+			name:    "tilde fence does not close with backticks",
+			content: "~~~\ncode\n```\nmore\n~~~\nafter",
+			want:    [][2]int{{0, 22}},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := Ranges(tt.content)
+			if len(got) != len(tt.want) {
+				t.Fatalf("Ranges() = %v, want %v", got, tt.want)
+			}
+			for i := range got {
+				if got[i] != tt.want[i] {
+					t.Errorf("Ranges()[%d] = %v, want %v", i, got[i], tt.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestReplaceOutside(t *testing.T) {
+	upper := func(s string) string {
+		b := []byte(s)
+		for i, c := range b {
+			if c >= 'a' && c <= 'z' {
+				b[i] = c - 32
+			}
+		}
+		return string(b)
+	}
+
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "no fences",
+			content: "hello world",
+			want:    "HELLO WORLD",
+		},
+		{
+			name:    "text around fence",
+			content: "before\n```\ncode\n```\nafter",
+			want:    "BEFORE\n```\ncode\n```\nAFTER",
+		},
+		{
+			name:    "multiple fences",
+			content: "aaa\n```\nxxx\n```\nbbb\n~~~\nyyy\n~~~\nccc",
+			want:    "AAA\n```\nxxx\n```\nBBB\n~~~\nyyy\n~~~\nCCC",
+		},
+		{
+			name:    "unclosed fence preserves code",
+			content: "before\n```\ncode",
+			want:    "BEFORE\n```\ncode",
+		},
+		{
+			name:    "only fenced content",
+			content: "```\ncode\n```",
+			want:    "```\ncode\n```",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ReplaceOutside(tt.content, upper)
+			if got != tt.want {
+				t.Errorf("ReplaceOutside() =\n%s\nwant:\n%s", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestStripFenced(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "no fences",
+			content: "hello $1 world",
+			want:    "hello $1 world",
+		},
+		{
+			name:    "strips fenced code",
+			content: "before $1\n```\n$2 inside\n```\nafter $3",
+			want:    "before $1\nafter $3",
+		},
+		{
+			name:    "multiple fences",
+			content: "a\n```\nx\n```\nb\n~~~\ny\n~~~\nc",
+			want:    "a\nb\nc",
+		},
+		{
+			name:    "unclosed fence",
+			content: "before\n```\n$1 inside",
+			want:    "before\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := StripFenced(tt.content)
+			if got != tt.want {
+				t.Errorf("StripFenced() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestInlineCodeRanges(t *testing.T) {
+	tests := []struct {
+		name string
+		s    string
+		want [][2]int
+	}{
+		{"no backticks", "hello world", nil},
+		{"single backtick span", "use `$1` here", [][2]int{{4, 8}}},
+		{"double backtick span", "use ``$1`` here", [][2]int{{4, 10}}},
+		{"multiple spans", "`$1` and `$2`", [][2]int{{0, 4}, {9, 13}}},
+		{"unmatched backtick", "use `$1 here", nil},
+		{"mismatched backtick counts", "use ``$1` here", nil},
+		{"empty inline content", "use `` `` here", [][2]int{{4, 9}}},
+		{"backticks inside double", "use ``foo`bar`` here", [][2]int{{4, 15}}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := inlineCodeRanges(tt.s)
+			if len(got) != len(tt.want) {
+				t.Fatalf("inlineCodeRanges() = %v, want %v", got, tt.want)
+			}
+			for i := range got {
+				if got[i] != tt.want[i] {
+					t.Errorf("inlineCodeRanges()[%d] = %v, want %v", i, got[i], tt.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestReplaceOutside_InlineCode(t *testing.T) {
+	upper := func(s string) string {
+		b := []byte(s)
+		for i, c := range b {
+			if c >= 'a' && c <= 'z' {
+				b[i] = c - 32
+			}
+		}
+		return string(b)
+	}
+
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "inline code preserved",
+			content: "use `code` here",
+			want:    "USE `code` HERE",
+		},
+		{
+			name:    "double backtick inline code",
+			content: "use ``co`de`` here",
+			want:    "USE ``co`de`` HERE",
+		},
+		{
+			name:    "mixed fenced and inline",
+			content: "before `x` mid\n```\nfenced\n```\nafter `y` end",
+			want:    "BEFORE `x` MID\n```\nfenced\n```\nAFTER `y` END",
+		},
+		{
+			name:    "only inline code",
+			content: "`code`",
+			want:    "`code`",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ReplaceOutside(tt.content, upper)
+			if got != tt.want {
+				t.Errorf("ReplaceOutside() =\n%s\nwant:\n%s", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestStripCode(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "no code",
+			content: "hello $1 world",
+			want:    "hello $1 world",
+		},
+		{
+			name:    "strips inline code",
+			content: "use `$1` and `$2` for positional args",
+			want:    "use  and  for positional args",
+		},
+		{
+			name:    "strips fenced and inline",
+			content: "before `$1`\n```\n$2 inside\n```\nafter",
+			want:    "before \nafter",
+		},
+		{
+			name:    "real world prompt template",
+			content: "Use $@ for all args.\n`$1`, `$2` for positional.\n```bash\necho $1\n```\n",
+			want:    "Use $@ for all args.\n,  for positional.\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := StripCode(tt.content)
+			if got != tt.want {
+				t.Errorf("StripCode() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

internal/kitsetup/setup.go

@@ -33,6 +33,10 @@ type AgentSetupOptions struct {
 	// CoreTools overrides the default core tool set. If empty, core.AllTools()
 	// is used. Allows SDK users to pass custom tools (e.g. with WithWorkDir).
 	CoreTools []fantasy.AgentTool
+	// DisableCoreTools, when true, prevents loading any core tools.
+	// If both DisableCoreTools is true and CoreTools is empty, the agent
+	// will have no tools (useful for simple chat completions).
+	DisableCoreTools bool
 	// ExtraTools are additional tools added alongside core, MCP, and extension
 	// tools. They do not replace the defaults — they extend them.
 	ExtraTools []fantasy.AgentTool
@@ -40,6 +44,34 @@ type AgentSetupOptions struct {
 	// wrapping. Used by the SDK hook system. Both wrappers compose:
 	// extension wrapper runs first (inner), then this wrapper (outer).
 	ToolWrapper func([]fantasy.AgentTool) []fantasy.AgentTool
+
+	// ProviderConfig, when non-nil, is used directly instead of calling
+	// BuildProviderConfig(). Callers that already hold viperInitMu can
+	// pre-build this and release the lock before calling SetupAgent, so the
+	// slow agent/MCP initialisation runs concurrently with other New() calls.
+	ProviderConfig *models.ProviderConfig
+	// Debug enables debug logging. When zero-value, viper is consulted.
+	// Only meaningful when ProviderConfig is also set.
+	Debug bool
+	// NoExtensions skips extension loading. When false, viper is consulted.
+	// Only meaningful when ProviderConfig is also set.
+	NoExtensions bool
+	// MaxSteps overrides the agent step limit. 0 means use viper value.
+	// Only meaningful when ProviderConfig is also set.
+	MaxSteps int
+	// StreamingEnabled controls streaming. Only meaningful when ProviderConfig
+	// is also set.
+	StreamingEnabled bool
+	// AuthHandler handles OAuth authorization for remote MCP servers.
+	// When set, remote transports are configured with OAuth support.
+	AuthHandler tools.MCPAuthHandler
+	// TokenStoreFactory, if non-nil, creates a custom token store for each
+	// remote MCP server's OAuth tokens. When nil, the default file-based
+	// token store is used.
+	TokenStoreFactory tools.TokenStoreFactory
+	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
+	// loading (successfully or with error). Called from the background goroutine.
+	OnMCPServerLoaded func(serverName string, toolCount int, err error)
 }
 
 // AgentSetupResult bundles the created agent and any debug logger so the caller
@@ -54,15 +86,17 @@ type AgentSetupResult struct {
 
 // BuildProviderConfig creates a *models.ProviderConfig from the current viper
 // state. All entry points (root, script, SDK) converge through this function.
+//
+// Generation parameter pointers (Temperature, TopP, etc.) are only set when
+// the user has explicitly configured them via CLI flag, environment variable,
+// or global config file. This allows per-model defaults from modelSettings
+// and customModels to fill in unset parameters downstream.
 func BuildProviderConfig() (*models.ProviderConfig, string, error) {
 	systemPrompt, err := config.LoadSystemPrompt(viper.GetString("system-prompt"))
 	if err != nil {
 		return nil, "", fmt.Errorf("failed to load system prompt: %w", err)
 	}
 
-	temperature := float32(viper.GetFloat64("temperature"))
-	topP := float32(viper.GetFloat64("top-p"))
-	topK := int32(viper.GetInt("top-k"))
 	numGPU := int32(viper.GetInt("num-gpu-layers"))
 	mainGPU := int32(viper.GetInt("main-gpu"))
 
@@ -72,9 +106,6 @@ func BuildProviderConfig() (*models.ProviderConfig, string, error) {
 		ProviderAPIKey: viper.GetString("provider-api-key"),
 		ProviderURL:    viper.GetString("provider-url"),
 		MaxTokens:      viper.GetInt("max-tokens"),
-		Temperature:    &temperature,
-		TopP:           &topP,
-		TopK:           &topK,
 		StopSequences:  viper.GetStringSlice("stop-sequences"),
 		NumGPU:         &numGPU,
 		MainGPU:        &mainGPU,
@@ -82,21 +113,66 @@ func BuildProviderConfig() (*models.ProviderConfig, string, error) {
 		ThinkingLevel:  models.ParseThinkingLevel(viper.GetString("thinking-level")),
 	}
 
+	// Only set generation parameter pointers when the user has explicitly
+	// provided a value. This leaves nil pointers for unset params, allowing
+	// per-model defaults (modelSettings / customModels params) to apply.
+	if viper.IsSet("temperature") {
+		v := float32(viper.GetFloat64("temperature"))
+		cfg.Temperature = &v
+	}
+	if viper.IsSet("top-p") {
+		v := float32(viper.GetFloat64("top-p"))
+		cfg.TopP = &v
+	}
+	if viper.IsSet("top-k") {
+		v := int32(viper.GetInt("top-k"))
+		cfg.TopK = &v
+	}
+	if viper.IsSet("frequency-penalty") {
+		v := float32(viper.GetFloat64("frequency-penalty"))
+		cfg.FrequencyPenalty = &v
+	}
+	if viper.IsSet("presence-penalty") {
+		v := float32(viper.GetFloat64("presence-penalty"))
+		cfg.PresencePenalty = &v
+	}
+
 	return cfg, systemPrompt, nil
 }
 
 // SetupAgent creates an agent from the current viper state + the provided
 // options. It wraps BuildProviderConfig and agent.CreateAgent.
 func SetupAgent(ctx context.Context, opts AgentSetupOptions) (*AgentSetupResult, error) {
-	modelConfig, systemPrompt, err := BuildProviderConfig()
-	if err != nil {
-		return nil, err
+	var modelConfig *models.ProviderConfig
+	var systemPrompt string
+
+	if opts.ProviderConfig != nil {
+		// Pre-built config supplied by caller (e.g. Kit.New after releasing
+		// viperInitMu). Use it directly — no viper reads needed here.
+		modelConfig = opts.ProviderConfig
+		systemPrompt = modelConfig.SystemPrompt
+	} else {
+		var err error
+		modelConfig, systemPrompt, err = BuildProviderConfig()
+		if err != nil {
+			return nil, err
+		}
 	}
 
+	// Resolve debug / no-extensions / max-steps / streaming: prefer explicit
+	// fields (set when ProviderConfig was pre-built) over viper fallback.
+	debugEnabled := opts.Debug || viper.GetBool("debug")
+	noExtensions := opts.NoExtensions || viper.GetBool("no-extensions")
+	maxSteps := opts.MaxSteps
+	if maxSteps == 0 {
+		maxSteps = viper.GetInt("max-steps")
+	}
+	streamingEnabled := opts.StreamingEnabled || viper.GetBool("stream")
+
 	// Create the appropriate debug logger.
 	var debugLogger tools.DebugLogger
 	var bufferedLogger *tools.BufferedDebugLogger
-	if viper.GetBool("debug") {
+	if debugEnabled {
 		if opts.UseBufferedLogger {
 			bufferedLogger = tools.NewBufferedDebugLogger(true)
 			debugLogger = bufferedLogger
@@ -108,7 +184,7 @@ func SetupAgent(ctx context.Context, opts AgentSetupOptions) (*AgentSetupResult,
 	// Load extensions unless --no-extensions is set.
 	var extRunner *extensions.Runner
 	var extCreationOpts extensionCreationOpts
-	if !viper.GetBool("no-extensions") {
+	if !noExtensions {
 		var extErr error
 		extRunner, extCreationOpts, extErr = loadExtensions()
 		if extErr != nil {
@@ -137,18 +213,22 @@ func SetupAgent(ctx context.Context, opts AgentSetupOptions) (*AgentSetupResult,
 	}
 
 	a, err := agent.CreateAgent(ctx, &agent.AgentCreationOptions{
-		ModelConfig:      modelConfig,
-		MCPConfig:        opts.MCPConfig,
-		SystemPrompt:     systemPrompt,
-		MaxSteps:         viper.GetInt("max-steps"),
-		StreamingEnabled: viper.GetBool("stream"),
-		ShowSpinner:      opts.ShowSpinner,
-		Quiet:            opts.Quiet,
-		SpinnerFunc:      opts.SpinnerFunc,
-		DebugLogger:      debugLogger,
-		CoreTools:        opts.CoreTools,
-		ToolWrapper:      toolWrapper,
-		ExtraTools:       extraTools,
+		ModelConfig:       modelConfig,
+		MCPConfig:         opts.MCPConfig,
+		SystemPrompt:      systemPrompt,
+		MaxSteps:          maxSteps,
+		StreamingEnabled:  streamingEnabled,
+		ShowSpinner:       opts.ShowSpinner,
+		Quiet:             opts.Quiet,
+		SpinnerFunc:       opts.SpinnerFunc,
+		DebugLogger:       debugLogger,
+		AuthHandler:       opts.AuthHandler,
+		TokenStoreFactory: opts.TokenStoreFactory,
+		CoreTools:         opts.CoreTools,
+		DisableCoreTools:  opts.DisableCoreTools,
+		ToolWrapper:       toolWrapper,
+		ExtraTools:        extraTools,
+		OnMCPServerLoaded: opts.OnMCPServerLoaded,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to create agent: %w", err)
@@ -187,7 +267,7 @@ func loadExtensions() (*extensions.Runner, extensionCreationOpts, error) {
 		return extensions.WrapToolsWithExtensions(tools, runner)
 	}
 
-	extTools := extensions.ExtensionToolsAsFantasy(runner.RegisteredTools(), runner)
+	extTools := extensions.ExtensionToolsAsLLMTools(runner.RegisteredTools(), runner)
 
 	return runner, extensionCreationOpts{
 		toolWrapper: wrapper,

internal/message/content.go

@@ -325,12 +325,6 @@ func UnmarshalParts(data []byte) ([]ContentPart, error) {
 // mixed TextPart and ToolCallPart content. Tool-role messages produce
 // ToolResultPart entries.
 func (m *Message) ToLLMMessages() []fantasy.Message {
-	return m.ToFantasyMessages()
-}
-
-// Deprecated: Use ToLLMMessages instead.
-// ToFantasyMessages converts a Message to one or more LLM message values.
-func (m *Message) ToFantasyMessages() []fantasy.Message {
 	switch m.Role {
 	case RoleAssistant:
 		var parts []fantasy.MessagePart
@@ -431,13 +425,6 @@ func (m *Message) ToFantasyMessages() []fantasy.Message {
 // FromLLMMessage converts an LLM message into our Message type,
 // extracting all content parts into the appropriate block types.
 func FromLLMMessage(msg fantasy.Message) Message {
-	return FromFantasyMessage(msg)
-}
-
-// Deprecated: Use FromLLMMessage instead.
-// FromFantasyMessage converts an LLM message into our Message type,
-// extracting all content parts into the appropriate block types.
-func FromFantasyMessage(msg fantasy.Message) Message {
 	m := Message{
 		Role:      MessageRole(msg.Role),
 		Parts:     make([]ContentPart, 0),

internal/models/custom.go

@@ -2,6 +2,8 @@ package models
 
 import (
 	"log"
+	"os"
+	"strings"
 
 	"github.com/spf13/viper"
 )
@@ -31,12 +33,14 @@ func loadCustomModelsFromConfig() map[string]ModelInfo {
 
 // modelConfigToModelInfo converts a CustomModelConfig to a ModelInfo.
 func modelConfigToModelInfo(modelID string, cfg CustomModelConfig) ModelInfo {
-	return ModelInfo{
+	info := ModelInfo{
 		ID:          modelID,
 		Name:        cfg.Name,
 		Attachment:  cfg.Attachment,
 		Reasoning:   cfg.Reasoning,
 		Temperature: cfg.Temperature,
+		BaseURL:     cfg.BaseURL,
+		APIKey:      cfg.APIKey,
 		Cost: Cost{
 			Input:  cfg.Cost.Input,
 			Output: cfg.Cost.Output,
@@ -46,19 +50,242 @@ func modelConfigToModelInfo(modelID string, cfg CustomModelConfig) ModelInfo {
 			Output:  cfg.Limit.Output,
 		},
 	}
+
+	// Convert custom model generation params if any are set.
+	if p := convertGenerationParams(cfg.Params); p != nil {
+		info.Params = p
+	}
+
+	return info
+}
+
+// LoadModelSettingsFromConfig loads per-model generation parameter overrides
+// from the config file. Keys are "provider/model" strings. Returns nil if
+// no model settings are configured.
+func LoadModelSettingsFromConfig() map[string]*GenerationParams {
+	if !viper.IsSet("modelSettings") {
+		return nil
+	}
+
+	var settings map[string]GenerationParamsConfig
+	if err := viper.UnmarshalKey("modelSettings", &settings); err != nil {
+		log.Printf("Warning: Failed to parse modelSettings: %v", err)
+		return nil
+	}
+
+	result := make(map[string]*GenerationParams, len(settings))
+	for modelKey, cfg := range settings {
+		if p := convertGenerationParams(cfg); p != nil {
+			result[modelKey] = p
+		}
+	}
+
+	return result
+}
+
+// convertGenerationParams converts a GenerationParamsConfig to a GenerationParams.
+// Returns nil if no parameters are set.
+func convertGenerationParams(cfg GenerationParamsConfig) *GenerationParams {
+	p := &GenerationParams{}
+	any := false
+
+	if cfg.MaxTokens != nil {
+		p.MaxTokens = cfg.MaxTokens
+		any = true
+	}
+	if cfg.Temperature != nil {
+		p.Temperature = cfg.Temperature
+		any = true
+	}
+	if cfg.TopP != nil {
+		p.TopP = cfg.TopP
+		any = true
+	}
+	if cfg.TopK != nil {
+		p.TopK = cfg.TopK
+		any = true
+	}
+	if cfg.FrequencyPenalty != nil {
+		p.FrequencyPenalty = cfg.FrequencyPenalty
+		any = true
+	}
+	if cfg.PresencePenalty != nil {
+		p.PresencePenalty = cfg.PresencePenalty
+		any = true
+	}
+	if len(cfg.StopSequences) > 0 {
+		p.StopSequences = cfg.StopSequences
+		any = true
+	}
+	if cfg.ThinkingLevel != "" {
+		p.ThinkingLevel = ParseThinkingLevel(cfg.ThinkingLevel)
+		any = true
+	}
+	if cfg.SystemPrompt != "" {
+		p.SystemPrompt = cfg.SystemPrompt
+		any = true
+	}
+
+	if !any {
+		return nil
+	}
+	return p
+}
+
+// ApplyModelSettings merges per-model generation parameter defaults from the
+// registry into a ProviderConfig. Model-level params are only applied for
+// fields where the user has not explicitly set a value (i.e., the
+// corresponding viper key is not set via CLI flag or global config).
+//
+// The lookup order is:
+//  1. modelSettings["provider/model"] from config (highest model-level priority)
+//  2. ModelInfo.Params from custom model definitions
+//
+// Both are overridden by explicit CLI flags / global config values.
+func ApplyModelSettings(config *ProviderConfig, modelInfo *ModelInfo) {
+	provider, modelName, err := ParseModelString(config.ModelString)
+	if err != nil {
+		return
+	}
+
+	// Collect model-level params: modelSettings override > custom model params.
+	// modelSettings takes priority because it's the more specific/intentional config.
+	var params *GenerationParams
+
+	// First check modelSettings from config.
+	if settings := LoadModelSettingsFromConfig(); settings != nil {
+		modelKey := provider + "/" + modelName
+		if p, ok := settings[modelKey]; ok {
+			params = p
+		}
+	}
+
+	// Fall back to ModelInfo.Params (from custom model definitions).
+	if params == nil && modelInfo != nil && modelInfo.Params != nil {
+		params = modelInfo.Params
+	}
+
+	if params == nil {
+		return
+	}
+
+	// Apply each parameter only when the user hasn't explicitly set it.
+	// We check viper.IsSet() which returns true only when the key was
+	// set via CLI flag, environment variable, or config file global section.
+
+	if params.MaxTokens != nil && !isExplicitlySet("max-tokens") {
+		config.MaxTokens = *params.MaxTokens
+	}
+	if params.Temperature != nil && !isExplicitlySet("temperature") {
+		config.Temperature = params.Temperature
+	}
+	if params.TopP != nil && !isExplicitlySet("top-p") {
+		config.TopP = params.TopP
+	}
+	if params.TopK != nil && !isExplicitlySet("top-k") {
+		config.TopK = params.TopK
+	}
+	if params.FrequencyPenalty != nil && !isExplicitlySet("frequency-penalty") {
+		config.FrequencyPenalty = params.FrequencyPenalty
+	}
+	if params.PresencePenalty != nil && !isExplicitlySet("presence-penalty") {
+		config.PresencePenalty = params.PresencePenalty
+	}
+	if len(params.StopSequences) > 0 && !isExplicitlySet("stop-sequences") {
+		config.StopSequences = params.StopSequences
+	}
+	if params.ThinkingLevel != "" && !isExplicitlySet("thinking-level") {
+		config.ThinkingLevel = params.ThinkingLevel
+	}
+	if params.SystemPrompt != "" && config.SystemPrompt == "" {
+		// Resolve file paths: if the value points to an existing file, read it.
+		// We check config.SystemPrompt == "" rather than isExplicitlySet because
+		// viper.BindPFlag causes IsSet to return true even for unset flags.
+		config.SystemPrompt = LoadSystemPromptValue(params.SystemPrompt)
+	}
+}
+
+// LoadSystemPromptValue resolves a system prompt value that may be either
+// inline text or a file path. If the value is a path to an existing file,
+// its contents are read and returned. Otherwise the string is returned as-is.
+// This mirrors config.LoadSystemPrompt but lives in the models package to
+// avoid circular dependencies.
+func LoadSystemPromptValue(input string) string {
+	if input == "" {
+		return ""
+	}
+	if info, err := os.Stat(input); err == nil && !info.IsDir() {
+		content, err := os.ReadFile(input)
+		if err != nil {
+			log.Printf("Warning: failed to read system prompt file %q: %v", input, err)
+			return input
+		}
+		return strings.TrimSpace(string(content))
+	}
+	return input
+}
+
+// isExplicitlySet returns true when the user has explicitly set a config key
+// via CLI flag, environment variable, or the global section of the config file.
+// Model-level defaults should not override explicitly set values.
+func isExplicitlySet(key string) bool {
+	// viper.IsSet returns true if the key has been set in any of the
+	// data stores (flag, env, config file, default). We need to check
+	// whether the value was set at the global config level (not just
+	// as a default). For generation params, the global config keys use
+	// hyphenated names (e.g. "max-tokens", "top-p").
+	//
+	// Since viper merges all sources, IsSet returns true even for config
+	// file values. This means global config file values (e.g.
+	// temperature: 0.7 at the top level) will correctly take precedence
+	// over model-level defaults, which is the desired behavior.
+	return viper.IsSet(key)
+}
+
+// GenerationParams holds per-model generation parameter defaults.
+// These are stored on ModelInfo and applied during provider creation.
+// Nil pointer fields mean "no model-level default" — the global config
+// or CLI flag value (if any) will be used instead.
+type GenerationParams struct {
+	MaxTokens        *int
+	Temperature      *float32
+	TopP             *float32
+	TopK             *int32
+	FrequencyPenalty *float32
+	PresencePenalty  *float32
+	StopSequences    []string
+	ThinkingLevel    ThinkingLevel
+	SystemPrompt     string // Per-model system prompt (inline text or file path)
 }
 
 // CustomModelConfig defines a custom model configuration loaded from the config file.
 // This is a duplicate here to avoid circular dependencies with internal/config.
 type CustomModelConfig struct {
-	Name        string      `json:"name" yaml:"name"`
-	Family      string      `json:"family,omitempty" yaml:"family,omitempty"`
-	Attachment  bool        `json:"attachment,omitempty" yaml:"attachment,omitempty"`
-	Reasoning   bool        `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
-	Temperature bool        `json:"temperature,omitempty" yaml:"temperature,omitempty"`
-	Knowledge   string      `json:"knowledge,omitempty" yaml:"knowledge,omitempty"`
-	Cost        CostConfig  `json:"cost" yaml:"cost"`
-	Limit       LimitConfig `json:"limit" yaml:"limit"`
+	Name        string                 `json:"name" yaml:"name"`
+	BaseURL     string                 `json:"baseUrl,omitempty" yaml:"baseUrl,omitempty"`
+	APIKey      string                 `json:"apiKey,omitempty" yaml:"apiKey,omitempty"`
+	Family      string                 `json:"family,omitempty" yaml:"family,omitempty"`
+	Attachment  bool                   `json:"attachment,omitempty" yaml:"attachment,omitempty"`
+	Reasoning   bool                   `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
+	Temperature bool                   `json:"temperature,omitempty" yaml:"temperature,omitempty"`
+	Knowledge   string                 `json:"knowledge,omitempty" yaml:"knowledge,omitempty"`
+	Cost        CostConfig             `json:"cost" yaml:"cost"`
+	Limit       LimitConfig            `json:"limit" yaml:"limit"`
+	Params      GenerationParamsConfig `json:"params,omitzero" yaml:"params,omitempty"`
+}
+
+// GenerationParamsConfig is the JSON/YAML-serializable form of generation
+// parameter defaults. Used in both customModels[].params and modelSettings[].
+type GenerationParamsConfig struct {
+	MaxTokens        *int     `json:"maxTokens,omitempty" yaml:"maxTokens,omitempty"`
+	Temperature      *float32 `json:"temperature,omitempty" yaml:"temperature,omitempty"`
+	TopP             *float32 `json:"topP,omitempty" yaml:"topP,omitempty"`
+	TopK             *int32   `json:"topK,omitempty" yaml:"topK,omitempty"`
+	FrequencyPenalty *float32 `json:"frequencyPenalty,omitempty" yaml:"frequencyPenalty,omitempty"`
+	PresencePenalty  *float32 `json:"presencePenalty,omitempty" yaml:"presencePenalty,omitempty"`
+	StopSequences    []string `json:"stopSequences,omitempty" yaml:"stopSequences,omitempty"`
+	ThinkingLevel    string   `json:"thinkingLevel,omitempty" yaml:"thinkingLevel,omitempty"`
+	SystemPrompt     string   `json:"systemPrompt,omitempty" yaml:"systemPrompt,omitempty"`
 }
 
 // CostConfig defines the pricing for a custom model.

internal/models/custom_test.go

@@ -0,0 +1,422 @@
+package models
+
+import (
+	"os"
+	"testing"
+
+	"github.com/spf13/viper"
+)
+
+func TestConvertGenerationParams(t *testing.T) {
+	t.Run("empty config returns nil", func(t *testing.T) {
+		cfg := GenerationParamsConfig{}
+		p := convertGenerationParams(cfg)
+		if p != nil {
+			t.Errorf("expected nil, got %+v", p)
+		}
+	})
+
+	t.Run("temperature only", func(t *testing.T) {
+		temp := float32(0.7)
+		cfg := GenerationParamsConfig{Temperature: &temp}
+		p := convertGenerationParams(cfg)
+		if p == nil {
+			t.Fatal("expected non-nil")
+		}
+		if p.Temperature == nil || *p.Temperature != 0.7 {
+			t.Errorf("expected temperature 0.7, got %v", p.Temperature)
+		}
+		if p.TopP != nil {
+			t.Errorf("expected nil TopP, got %v", p.TopP)
+		}
+	})
+
+	t.Run("all params set", func(t *testing.T) {
+		maxTokens := 8192
+		temp := float32(0.5)
+		topP := float32(0.9)
+		topK := int32(50)
+		freqPenalty := float32(0.1)
+		presPenalty := float32(0.2)
+		cfg := GenerationParamsConfig{
+			MaxTokens:        &maxTokens,
+			Temperature:      &temp,
+			TopP:             &topP,
+			TopK:             &topK,
+			FrequencyPenalty: &freqPenalty,
+			PresencePenalty:  &presPenalty,
+			StopSequences:    []string{"STOP"},
+			ThinkingLevel:    "high",
+		}
+		p := convertGenerationParams(cfg)
+		if p == nil {
+			t.Fatal("expected non-nil")
+		}
+		if p.MaxTokens == nil || *p.MaxTokens != 8192 {
+			t.Errorf("expected maxTokens 8192, got %v", p.MaxTokens)
+		}
+		if p.Temperature == nil || *p.Temperature != 0.5 {
+			t.Errorf("expected temperature 0.5, got %v", p.Temperature)
+		}
+		if p.TopP == nil || *p.TopP != 0.9 {
+			t.Errorf("expected topP 0.9, got %v", p.TopP)
+		}
+		if p.TopK == nil || *p.TopK != 50 {
+			t.Errorf("expected topK 50, got %v", p.TopK)
+		}
+		if p.FrequencyPenalty == nil || *p.FrequencyPenalty != 0.1 {
+			t.Errorf("expected frequencyPenalty 0.1, got %v", p.FrequencyPenalty)
+		}
+		if p.PresencePenalty == nil || *p.PresencePenalty != 0.2 {
+			t.Errorf("expected presencePenalty 0.2, got %v", p.PresencePenalty)
+		}
+		if len(p.StopSequences) != 1 || p.StopSequences[0] != "STOP" {
+			t.Errorf("expected stop sequences [STOP], got %v", p.StopSequences)
+		}
+		if p.ThinkingLevel != ThinkingHigh {
+			t.Errorf("expected thinking level high, got %v", p.ThinkingLevel)
+		}
+	})
+
+	t.Run("thinking level parsing", func(t *testing.T) {
+		cfg := GenerationParamsConfig{ThinkingLevel: "medium"}
+		p := convertGenerationParams(cfg)
+		if p == nil {
+			t.Fatal("expected non-nil")
+		}
+		if p.ThinkingLevel != ThinkingMedium {
+			t.Errorf("expected thinking level medium, got %v", p.ThinkingLevel)
+		}
+	})
+	t.Run("system prompt only", func(t *testing.T) {
+		cfg := GenerationParamsConfig{SystemPrompt: "You are helpful."}
+		p := convertGenerationParams(cfg)
+		if p == nil {
+			t.Fatal("expected non-nil")
+		}
+		if p.SystemPrompt != "You are helpful." {
+			t.Errorf("expected system prompt, got %q", p.SystemPrompt)
+		}
+	})
+}
+
+func TestModelConfigToModelInfoWithParams(t *testing.T) {
+	temp := float32(0.8)
+	topP := float32(0.95)
+	cfg := CustomModelConfig{
+		Name:        "Test Model",
+		BaseURL:     "http://localhost:8080/v1",
+		Temperature: true,
+		Params: GenerationParamsConfig{
+			Temperature: &temp,
+			TopP:        &topP,
+		},
+	}
+
+	info := modelConfigToModelInfo("test-model", cfg)
+
+	if info.Params == nil {
+		t.Fatal("expected non-nil Params")
+	}
+	if info.Params.Temperature == nil || *info.Params.Temperature != 0.8 {
+		t.Errorf("expected temperature 0.8, got %v", info.Params.Temperature)
+	}
+	if info.Params.TopP == nil || *info.Params.TopP != 0.95 {
+		t.Errorf("expected topP 0.95, got %v", info.Params.TopP)
+	}
+}
+
+func TestModelConfigToModelInfoWithoutParams(t *testing.T) {
+	cfg := CustomModelConfig{
+		Name:    "Test Model",
+		BaseURL: "http://localhost:8080/v1",
+	}
+
+	info := modelConfigToModelInfo("test-model", cfg)
+
+	if info.Params != nil {
+		t.Errorf("expected nil Params, got %+v", info.Params)
+	}
+}
+
+func TestApplyModelSettings(t *testing.T) {
+	// Save and restore viper state.
+	originalViper := viper.AllSettings()
+	defer func() {
+		viper.Reset()
+		for k, v := range originalViper {
+			viper.Set(k, v)
+		}
+	}()
+
+	t.Run("applies model params when not explicitly set", func(t *testing.T) {
+		viper.Reset()
+
+		temp := float32(0.8)
+		topK := int32(50)
+		maxTokens := 4096
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				Temperature: &temp,
+				TopK:        &topK,
+				MaxTokens:   &maxTokens,
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		if config.Temperature == nil || *config.Temperature != 0.8 {
+			t.Errorf("expected temperature 0.8, got %v", config.Temperature)
+		}
+		if config.TopK == nil || *config.TopK != 50 {
+			t.Errorf("expected topK 50, got %v", config.TopK)
+		}
+		if config.MaxTokens != 4096 {
+			t.Errorf("expected maxTokens 4096, got %d", config.MaxTokens)
+		}
+	})
+
+	t.Run("explicit viper values take precedence", func(t *testing.T) {
+		viper.Reset()
+		viper.Set("temperature", 0.3)
+
+		temp := float32(0.8)
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				Temperature: &temp,
+			},
+		}
+
+		explicitTemp := float32(0.3)
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+			Temperature: &explicitTemp,
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		// Temperature should NOT be overridden because it's explicitly set in viper
+		if config.Temperature == nil || *config.Temperature != 0.3 {
+			t.Errorf("expected temperature 0.3 (explicit), got %v", config.Temperature)
+		}
+	})
+
+	t.Run("nil model info is safe", func(t *testing.T) {
+		viper.Reset()
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		// Should not panic
+		ApplyModelSettings(config, nil)
+
+		if config.Temperature != nil {
+			t.Errorf("expected nil temperature, got %v", config.Temperature)
+		}
+	})
+
+	t.Run("model info without params is safe", func(t *testing.T) {
+		viper.Reset()
+
+		modelInfo := &ModelInfo{ID: "test-model"}
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		if config.Temperature != nil {
+			t.Errorf("expected nil temperature, got %v", config.Temperature)
+		}
+	})
+
+	t.Run("modelSettings from viper takes priority over ModelInfo.Params", func(t *testing.T) {
+		viper.Reset()
+
+		// Set up modelSettings in viper (simulating config file)
+		viper.Set("modelSettings", map[string]any{
+			"custom/test-model": map[string]any{
+				"temperature": 0.5,
+				"topK":        30,
+			},
+		})
+
+		// ModelInfo has different params
+		temp := float32(0.8)
+		topK := int32(50)
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				Temperature: &temp,
+				TopK:        &topK,
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		// modelSettings should win over ModelInfo.Params
+		if config.Temperature == nil || *config.Temperature != 0.5 {
+			t.Errorf("expected temperature 0.5 (from modelSettings), got %v", config.Temperature)
+		}
+		if config.TopK == nil || *config.TopK != 30 {
+			t.Errorf("expected topK 30 (from modelSettings), got %v", config.TopK)
+		}
+	})
+
+	t.Run("stop sequences applied from model params", func(t *testing.T) {
+		viper.Reset()
+
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				StopSequences: []string{"STOP", "END"},
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		if len(config.StopSequences) != 2 || config.StopSequences[0] != "STOP" {
+			t.Errorf("expected stop sequences [STOP END], got %v", config.StopSequences)
+		}
+	})
+
+	t.Run("thinking level applied from model params", func(t *testing.T) {
+		viper.Reset()
+
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				ThinkingLevel: ThinkingHigh,
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		if config.ThinkingLevel != ThinkingHigh {
+			t.Errorf("expected thinking level high, got %v", config.ThinkingLevel)
+		}
+	})
+
+	t.Run("system prompt applied from model params", func(t *testing.T) {
+		viper.Reset()
+
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				SystemPrompt: "You are a coding assistant.",
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		if config.SystemPrompt != "You are a coding assistant." {
+			t.Errorf("expected system prompt to be set, got %q", config.SystemPrompt)
+		}
+	})
+
+	t.Run("explicit system prompt takes precedence", func(t *testing.T) {
+		viper.Reset()
+
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				SystemPrompt: "Model-specific prompt",
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString:  "custom/test-model",
+			SystemPrompt: "Global prompt",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		// Global system prompt should NOT be overridden because config
+		// already has a non-empty SystemPrompt.
+		if config.SystemPrompt != "Global prompt" {
+			t.Errorf("expected global prompt preserved, got %q", config.SystemPrompt)
+		}
+	})
+
+	t.Run("system prompt from file path", func(t *testing.T) {
+		viper.Reset()
+
+		// Create a temp file with a system prompt
+		tmpFile, err := os.CreateTemp("", "kit-test-prompt-*.txt")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer func() { _ = os.Remove(tmpFile.Name()) }()
+		if _, err := tmpFile.WriteString("  Prompt from file  "); err != nil {
+			t.Fatal(err)
+		}
+		_ = tmpFile.Close()
+
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				SystemPrompt: tmpFile.Name(),
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		if config.SystemPrompt != "Prompt from file" {
+			t.Errorf("expected trimmed file content, got %q", config.SystemPrompt)
+		}
+	})
+
+	t.Run("modelSettings system prompt overrides custom model params", func(t *testing.T) {
+		viper.Reset()
+
+		viper.Set("modelSettings", map[string]any{
+			"custom/test-model": map[string]any{
+				"systemPrompt": "From modelSettings",
+			},
+		})
+
+		modelInfo := &ModelInfo{
+			ID: "test-model",
+			Params: &GenerationParams{
+				SystemPrompt: "From custom model",
+			},
+		}
+
+		config := &ProviderConfig{
+			ModelString: "custom/test-model",
+		}
+
+		ApplyModelSettings(config, modelInfo)
+
+		if config.SystemPrompt != "From modelSettings" {
+			t.Errorf("expected modelSettings prompt, got %q", config.SystemPrompt)
+		}
+	})
+}

internal/models/providers.go

@@ -10,7 +10,6 @@ import (
 	"maps"
 	"net/http"
 	"os"
-	"regexp"
 	"strings"
 	"time"
 
@@ -26,7 +25,6 @@ import (
 	openaisdk "github.com/charmbracelet/openai-go"
 
 	"github.com/mark3labs/kit/internal/auth"
-	"github.com/mark3labs/kit/internal/ui/progress"
 )
 
 const (
@@ -144,20 +142,28 @@ func ParseThinkingLevel(s string) ThinkingLevel {
 
 // ProviderConfig holds configuration for creating LLM providers.
 type ProviderConfig struct {
-	ModelString    string
-	SystemPrompt   string
-	ProviderAPIKey string
-	ProviderURL    string
-	MaxTokens      int
-	Temperature    *float32
-	TopP           *float32
-	TopK           *int32
-	StopSequences  []string
-	NumGPU         *int32
-	MainGPU        *int32
-	TLSSkipVerify  bool
-	ThinkingLevel  ThinkingLevel
-	DisableCaching bool // Opt-out: set to true to disable automatic prompt caching
+	ModelString      string
+	SystemPrompt     string
+	ProviderAPIKey   string
+	ProviderURL      string
+	MaxTokens        int
+	Temperature      *float32
+	TopP             *float32
+	TopK             *int32
+	FrequencyPenalty *float32
+	PresencePenalty  *float32
+	StopSequences    []string
+	NumGPU           *int32
+	MainGPU          *int32
+	TLSSkipVerify    bool
+	ThinkingLevel    ThinkingLevel
+	DisableCaching   bool // Opt-out: set to true to disable automatic prompt caching
+
+	// ProgressReaderFunc, when set, wraps an io.Reader with progress display
+	// for long operations like Ollama model pulls. The returned io.ReadCloser
+	// must be closed when done. When nil, the raw reader is consumed directly
+	// with no progress UI.
+	ProgressReaderFunc func(io.Reader) io.ReadCloser
 }
 
 // ProviderResult contains the result of provider creation.
@@ -240,6 +246,11 @@ func CreateProvider(ctx context.Context, config *ProviderConfig) (*ProviderResul
 		validateModelConfig(config, modelInfo)
 	}
 
+	// Apply per-model generation parameter defaults. Model-level params are
+	// only applied for fields where the user hasn't explicitly set a value
+	// via CLI flag or global config.
+	ApplyModelSettings(config, modelInfo)
+
 	// Create the base provider
 	var result *ProviderResult
 	var createErr error
@@ -525,13 +536,13 @@ func buildOpenAIProviderOptions(config *ProviderConfig, modelName string) fantas
 func thinkingLevelToReasoningEffort(level ThinkingLevel) *openai.ReasoningEffort {
 	switch level {
 	case ThinkingMinimal:
-		return openai.ReasoningEffortOption(openai.ReasoningEffortMinimal)
+		return new(openai.ReasoningEffortMinimal)
 	case ThinkingLow:
-		return openai.ReasoningEffortOption(openai.ReasoningEffortLow)
+		return new(openai.ReasoningEffortLow)
 	case ThinkingMedium:
-		return openai.ReasoningEffortOption(openai.ReasoningEffortMedium)
+		return new(openai.ReasoningEffortMedium)
 	case ThinkingHigh:
-		return openai.ReasoningEffortOption(openai.ReasoningEffortHigh)
+		return new(openai.ReasoningEffortHigh)
 	default:
 		return nil
 	}
@@ -1000,139 +1011,29 @@ func createVercelProvider(ctx context.Context, config *ProviderConfig, modelName
 	return &ProviderResult{Model: model}, nil
 }
 
-// thinkTagRegex matches <think>...</think> tags for extracting reasoning content
-// from models that wrap thinking in XML-like tags (e.g., Qwen, DeepSeek).
-var thinkTagRegex = regexp.MustCompile(`(?s)<think>(.*?)</think>`)
-
-// customExtraContentFunc extracts reasoning from <think> tags in the content field.
-// This handles models like Qwen and DeepSeek that return reasoning wrapped in XML tags
-// rather than using a separate reasoning_content field.
-func customExtraContentFunc(choice openaisdk.ChatCompletionChoice) []fantasy.Content {
-	var content []fantasy.Content
-	if choice.Message.Content == "" {
-		return content
-	}
-
-	// Check for <think> tags in the content
-	matches := thinkTagRegex.FindStringSubmatch(choice.Message.Content)
-	if len(matches) > 1 {
-		// Found reasoning content in <think> tags
-		reasoning := strings.TrimSpace(matches[1])
-		if reasoning != "" {
-			content = append(content, fantasy.ReasoningContent{
-				Text: reasoning,
-			})
-		}
-	}
-
-	return content
-}
-
-// customStreamExtraFunc handles streaming responses with <think> tags.
-// It extracts reasoning content and emits proper reasoning events.
-func customStreamExtraFunc(
-	chunk openaisdk.ChatCompletionChunk,
-	yield func(fantasy.StreamPart) bool,
-	ctx map[string]any,
-) (map[string]any, bool) {
-	if len(chunk.Choices) == 0 {
-		return ctx, true
-	}
-
-	const reasoningStartedKey = "reasoning_started"
-	const reasoningBufferKey = "reasoning_buffer"
-	const inThinkTagKey = "in_think_tag"
-
-	reasoningStarted, _ := ctx[reasoningStartedKey].(bool)
-	inThinkTag, _ := ctx[inThinkTagKey].(bool)
-	reasoningBuffer, _ := ctx[reasoningBufferKey].(string)
-
-	for i, choice := range chunk.Choices {
-		content := choice.Delta.Content
-		if content == "" {
-			continue
-		}
-
-		// Check for <think> tag start
-		if strings.Contains(content, "<think>") {
-			inThinkTag = true
-			ctx[inThinkTagKey] = true
-
-			// Emit reasoning start event
-			if !reasoningStarted {
-				reasoningStarted = true
-				ctx[reasoningStartedKey] = true
-				if !yield(fantasy.StreamPart{
-					Type: fantasy.StreamPartTypeReasoningStart,
-					ID:   fmt.Sprintf("%d", i),
-				}) {
-					return ctx, false
-				}
-			}
-
-			// Extract content after <think>
-			parts := strings.SplitN(content, "<think>", 2)
-			if len(parts) > 1 && parts[1] != "" {
-				reasoningBuffer += parts[1]
-				ctx[reasoningBufferKey] = reasoningBuffer
-			}
-			continue
-		}
-
-		// Check for </think> tag end
-		if strings.Contains(content, "</think>") {
-			inThinkTag = false
-			ctx[inThinkTagKey] = false
-
-			// Extract content before </think>
-			parts := strings.SplitN(content, "</think>", 2)
-			if len(parts) > 0 {
-				reasoningBuffer += parts[0]
-			}
-
-			// Emit the accumulated reasoning
-			if reasoningBuffer != "" {
-				if !yield(fantasy.StreamPart{
-					Type:  fantasy.StreamPartTypeReasoningDelta,
-					ID:    fmt.Sprintf("%d", i),
-					Delta: reasoningBuffer,
-				}) {
-					return ctx, false
-				}
-				ctx[reasoningBufferKey] = ""
-			}
-
-			// Emit reasoning end
-			if !yield(fantasy.StreamPart{
-				Type: fantasy.StreamPartTypeReasoningEnd,
-				ID:   fmt.Sprintf("%d", i),
-			}) {
-				return ctx, false
-			}
-			continue
-		}
-
-		// Accumulate reasoning content while in think tag
-		if inThinkTag {
-			reasoningBuffer += content
-			ctx[reasoningBufferKey] = reasoningBuffer
-		}
-	}
-
-	return ctx, true
-}
-
 // customToPromptFunc converts prompts to OpenAI format using the default conversion.
 func customToPromptFunc(prompt fantasy.Prompt, systemPrompt, user string) ([]openaisdk.ChatCompletionMessageParamUnion, []fantasy.CallWarning) {
 	return openai.DefaultToPrompt(prompt, systemPrompt, user)
 }
 
 func createCustomProvider(ctx context.Context, config *ProviderConfig, modelName string) (*ProviderResult, error) {
-	if config.ProviderURL == "" {
-		return nil, fmt.Errorf("custom provider requires --provider-url")
+	// Resolve base URL: per-model override > global provider-url flag/config
+	registry := GetGlobalRegistry()
+	modelInfo := registry.LookupModel("custom", modelName)
+
+	baseURL := config.ProviderURL
+	if modelInfo != nil && modelInfo.BaseURL != "" {
+		baseURL = modelInfo.BaseURL
+	}
+
+	if baseURL == "" {
+		return nil, fmt.Errorf("custom provider requires --provider-url or a baseUrl in the model config")
 	}
 
 	apiKey := config.ProviderAPIKey
+	if modelInfo != nil && modelInfo.APIKey != "" {
+		apiKey = modelInfo.APIKey
+	}
 	if apiKey == "" {
 		apiKey = os.Getenv("CUSTOM_API_KEY")
 	}
@@ -1141,15 +1042,13 @@ func createCustomProvider(ctx context.Context, config *ProviderConfig, modelName
 		apiKey = "custom"
 	}
 
-	// Use the openai provider directly with custom hooks to handle <think> tags
-	// from models like Qwen and DeepSeek that wrap reasoning in XML tags.
+	// <think> tag extraction is handled transparently at the agent layer,
+	// so no provider-level hooks are needed here.
 	var opts []openai.Option
-	opts = append(opts, openai.WithBaseURL(config.ProviderURL))
+	opts = append(opts, openai.WithBaseURL(baseURL))
 	opts = append(opts, openai.WithAPIKey(apiKey))
 	opts = append(opts, openai.WithName("custom"))
 	opts = append(opts, openai.WithLanguageModelOptions(
-		openai.WithLanguageModelExtraContentFunc(customExtraContentFunc),
-		openai.WithLanguageModelStreamExtraFunc(customStreamExtraFunc),
 		openai.WithLanguageModelToPromptFunc(customToPromptFunc),
 	))
 
@@ -1234,7 +1133,7 @@ func loadOllamaModelWithFallback(ctx context.Context, baseURL, modelName string,
 	// Phase 1: Check if model exists locally
 	if err := checkOllamaModelExists(client, baseURL, modelName); err != nil {
 		// Phase 2: Pull model if not found
-		if err := pullOllamaModel(ctx, client, baseURL, modelName); err != nil {
+		if err := pullOllamaModel(ctx, client, baseURL, modelName, config.ProgressReaderFunc); err != nil {
 			return nil, fmt.Errorf("failed to pull model %s: %v", modelName, err)
 		}
 	}
@@ -1277,6 +1176,12 @@ func buildOllamaOptions(config *ProviderConfig) map[string]any {
 	if config.TopK != nil {
 		options["top_k"] = int(*config.TopK)
 	}
+	if config.FrequencyPenalty != nil {
+		options["frequency_penalty"] = *config.FrequencyPenalty
+	}
+	if config.PresencePenalty != nil {
+		options["presence_penalty"] = *config.PresencePenalty
+	}
 	if len(config.StopSequences) > 0 {
 		options["stop"] = config.StopSequences
 	}
@@ -1317,11 +1222,7 @@ func checkOllamaModelExists(client *http.Client, baseURL, modelName string) erro
 	return nil
 }
 
-func pullOllamaModel(ctx context.Context, client *http.Client, baseURL, modelName string) error {
-	return pullOllamaModelWithProgress(ctx, client, baseURL, modelName, true)
-}
-
-func pullOllamaModelWithProgress(ctx context.Context, client *http.Client, baseURL, modelName string, showProgress bool) error {
+func pullOllamaModel(ctx context.Context, client *http.Client, baseURL, modelName string, progressFn func(io.Reader) io.ReadCloser) error {
 	reqBody := map[string]string{"name": modelName}
 	jsonBody, _ := json.Marshal(reqBody)
 
@@ -1345,10 +1246,10 @@ func pullOllamaModelWithProgress(ctx context.Context, client *http.Client, baseU
 		return fmt.Errorf("failed to pull model (status %d): %s", resp.StatusCode, string(body))
 	}
 
-	if showProgress {
-		progressReader := progress.NewProgressReader(resp.Body)
-		defer func() { _ = progressReader.Close() }()
-		_, err = io.ReadAll(progressReader)
+	if progressFn != nil {
+		pr := progressFn(resp.Body)
+		defer func() { _ = pr.Close() }()
+		_, err = io.ReadAll(pr)
 	} else {
 		_, err = io.ReadAll(resp.Body)
 	}

internal/models/registry.go

@@ -24,6 +24,13 @@ type ModelInfo struct {
 	Cost        Cost
 	Limit       Limit
 	ProviderNPM string // Model-specific provider npm override (e.g. "@ai-sdk/anthropic")
+	BaseURL     string // Per-model base URL override (custom models only)
+	APIKey      string // Per-model API key override (custom models only)
+
+	// Params holds per-model generation parameter defaults. These are applied
+	// when the user hasn't explicitly set the corresponding CLI flag or global
+	// config value. Nil pointer fields mean "no model-level default".
+	Params *GenerationParams
 }
 
 // SupportsCaching returns true if this model family supports prompt caching.
@@ -234,6 +241,18 @@ func (r *ModelsRegistry) LookupModel(provider, modelID string) *ModelInfo {
 	return &modelInfo
 }
 
+// LookupModelForSettings is a convenience function that parses a
+// "provider/model" string and looks up the ModelInfo in the global registry.
+// Returns nil when the model string is invalid or the model is unknown.
+// Used by Kit.SetModel to pre-apply per-model settings before CreateProvider.
+func LookupModelForSettings(modelString string) *ModelInfo {
+	provider, modelName, err := ParseModelString(modelString)
+	if err != nil {
+		return nil
+	}
+	return GetGlobalRegistry().LookupModel(provider, modelName)
+}
+
 // getRequiredEnvVars returns the required environment variables for a provider.
 func (r *ModelsRegistry) getRequiredEnvVars(provider string) ([]string, error) {
 	providerInfo, exists := r.providers[provider]
@@ -360,15 +379,10 @@ func (r *ModelsRegistry) GetLLMProviders() []string {
 	return providers
 }
 
-// Deprecated: Use GetLLMProviders instead.
-func (r *ModelsRegistry) GetFantasyProviders() []string {
-	return r.GetLLMProviders()
-}
-
 // isProviderLLMSupported checks if a provider can be used with the LLM layer.
 func isProviderLLMSupported(providerID string, info *ProviderInfo) bool {
-	// Ollama is always supported (via openaicompat pointed at localhost)
-	if providerID == "ollama" {
+	// Ollama and custom are always supported (model names are user-defined).
+	if providerID == "ollama" || providerID == "custom" {
 		return true
 	}
 
@@ -400,6 +414,52 @@ func (r *ModelsRegistry) GetProviderInfo(provider string) *ProviderInfo {
 	return &info
 }
 
+// ValidateModelString checks whether a model string is well-formed and refers
+// to a known provider. It returns a user-friendly error with suggestions when
+// the model or provider is unrecognised. Passing validation does not guarantee
+// that API authentication will succeed — it only catches obvious mistakes
+// (typos, missing provider prefix, non-existent provider names) early so that
+// callers such as subagent spawning can return fast feedback.
+//
+// Unknown models under a known provider are allowed (the provider API is the
+// authority), but a completely unknown provider is rejected.
+func (r *ModelsRegistry) ValidateModelString(modelString string) error {
+	provider, modelName, err := ParseModelString(modelString)
+	if err != nil {
+		return err
+	}
+
+	// Ollama and custom are always valid — model names are user-defined.
+	if provider == "ollama" || provider == "custom" {
+		return nil
+	}
+
+	// Check if the provider exists in the registry.
+	providerInfo := r.GetProviderInfo(provider)
+	if providerInfo == nil {
+		known := r.GetSupportedProviders()
+		return fmt.Errorf(
+			"unknown provider %q in model string %q. Known providers: %s",
+			provider, modelString, strings.Join(known, ", "),
+		)
+	}
+
+	// Provider exists — check if the model is known. An unknown model is
+	// only a warning (the provider API decides), but we surface suggestions
+	// so the caller can self-correct.
+	if r.LookupModel(provider, modelName) == nil {
+		if suggestions := r.SuggestModels(provider, modelName); len(suggestions) > 0 {
+			return fmt.Errorf(
+				"model %q not found for provider %s. Did you mean one of: %s",
+				modelName, provider, strings.Join(suggestions, ", "),
+			)
+		}
+		// No suggestions — let it through; the provider API is the authority.
+	}
+
+	return nil
+}
+
 // Global registry instance
 var globalRegistry = NewModelsRegistry()
 

internal/models/registry_test.go

@@ -0,0 +1,92 @@
+package models
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateModelString(t *testing.T) {
+	registry := GetGlobalRegistry()
+
+	tests := []struct {
+		name      string
+		model     string
+		wantErr   bool
+		errSubstr string // expected substring in error message (empty = don't check)
+	}{
+		{
+			name:    "valid anthropic model",
+			model:   "anthropic/claude-sonnet-4-6",
+			wantErr: false,
+		},
+		{
+			name:      "missing provider prefix",
+			model:     "claude-sonnet-4-6",
+			wantErr:   true,
+			errSubstr: "invalid model format",
+		},
+		{
+			name:      "empty string",
+			model:     "",
+			wantErr:   true,
+			errSubstr: "invalid model format",
+		},
+		{
+			name:      "unknown provider",
+			model:     "fakeprovider/some-model",
+			wantErr:   true,
+			errSubstr: "unknown provider",
+		},
+		{
+			name:    "ollama always valid",
+			model:   "ollama/llama3",
+			wantErr: false,
+		},
+		{
+			name:    "custom always valid",
+			model:   "custom/my-fine-tune",
+			wantErr: false,
+		},
+		{
+			name:      "empty provider",
+			model:     "/claude-sonnet-4-6",
+			wantErr:   true,
+			errSubstr: "invalid model format",
+		},
+		{
+			name:      "empty model name",
+			model:     "anthropic/",
+			wantErr:   true,
+			errSubstr: "invalid model format",
+		},
+		{
+			name:    "unknown model under known provider (no suggestions)",
+			model:   "anthropic/totally-unknown-xyz-999",
+			wantErr: false, // no suggestions → passes through
+		},
+		{
+			name:      "typo model under known provider with suggestions",
+			model:     "anthropic/claude-sonet", // misspelled "sonnet"
+			wantErr:   true,
+			errSubstr: "Did you mean",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := registry.ValidateModelString(tt.model)
+			if tt.wantErr && err == nil {
+				t.Errorf("ValidateModelString(%q) = nil, want error", tt.model)
+			}
+			if !tt.wantErr && err != nil {
+				t.Errorf("ValidateModelString(%q) = %v, want nil", tt.model, err)
+			}
+			if tt.errSubstr != "" && err != nil {
+				if !strings.Contains(err.Error(), tt.errSubstr) {
+					t.Errorf("ValidateModelString(%q) error = %q, want substring %q",
+						tt.model, err.Error(), tt.errSubstr)
+				}
+			}
+		})
+	}
+}

internal/prompts/loader.go

@@ -2,11 +2,10 @@ package prompts
 
 import (
 	"fmt"
+	"log"
 	"os"
 	"path/filepath"
 	"strings"
-
-	"github.com/charmbracelet/log"
 )
 
 // LoadOptions configures how templates are discovered and loaded.
@@ -74,10 +73,7 @@ func LoadAll(opts LoadOptions) ([]*PromptTemplate, []Diagnostic, error) {
 					DroppedPath: tpl.FilePath,
 					Reason:      fmt.Sprintf("template from %s overridden by %s", source, existing.Source),
 				})
-				log.Debug("template collision",
-					"name", tpl.Name,
-					"dropped", tpl.FilePath,
-					"kept", existing.FilePath)
+				log.Printf("DEBUG template collision: name=%s dropped=%s kept=%s", tpl.Name, tpl.FilePath, existing.FilePath)
 			} else {
 				tpl.Source = source
 				seen[tpl.Name] = tpl

internal/prompts/template.go

@@ -7,10 +7,12 @@ import (
 	"regexp"
 	"strconv"
 	"strings"
+
+	"github.com/mark3labs/kit/internal/fences"
 )
 
 // PromptTemplate is a named prompt template with shell-style argument placeholders.
-// It supports Pi-style $1, $2, $@, $ARGUMENTS, ${@:N}, ${@:N:L} syntax.
+// It supports Pi-style $1, $2, $@, $+, $ARGUMENTS, ${@:N}, ${@:N:L} syntax.
 type PromptTemplate struct {
 	// Name is the human-readable identifier for this template.
 	Name string
@@ -120,19 +122,28 @@ func ParseCommandArgs(input string) []string {
 
 // argPlaceholder matches shell-style argument placeholders:
 //   - $1, $2, etc. - positional arguments
-//   - $@ - all arguments
+//   - $@ - all arguments (zero or more)
+//   - $+ - all arguments (one or more required)
 //   - $ARGUMENTS - all arguments (alias for $@)
 //   - ${@:N} - arguments from N onwards
 //   - ${@:N:L} - L arguments starting from N
-var argPlaceholder = regexp.MustCompile(`\$\{(\d+)\}|\$\{(\d+):(\d+)\}|\$\{ARGUMENTS\}|\$\{@(:\d+)?(:\d+)?\}|\$(\d+)|\$@|\$ARGUMENTS`)
+var argPlaceholder = regexp.MustCompile(`\$\{(\d+)\}|\$\{(\d+):(\d+)\}|\$\{ARGUMENTS\}|\$\{@(:\d+)?(:\d+)?\}|\$(\d+)|\$@|\$\+|\$ARGUMENTS`)
 
 // SubstituteArgs replaces argument placeholders in content with values from args.
 // Supported placeholders:
 //   - $N, ${N} - the Nth argument (1-indexed)
-//   - $@, $ARGUMENTS, ${ARGUMENTS} - all arguments joined with spaces
+//   - $@, $+, $ARGUMENTS, ${ARGUMENTS} - all arguments joined with spaces
 //   - ${@:N} - arguments from index N onwards (0-indexed)
 //   - ${@:N:L} - L arguments starting from index N (0-indexed)
 func SubstituteArgs(content string, args []string) string {
+	return fences.ReplaceOutside(content, func(segment string) string {
+		return substituteArgsInSegment(segment, args)
+	})
+}
+
+// substituteArgsInSegment performs argument substitution on a single text
+// segment that is known to be outside fenced code blocks.
+func substituteArgsInSegment(content string, args []string) string {
 	return argPlaceholder.ReplaceAllStringFunc(content, func(match string) string {
 		// Check for ${N} or ${N:M} format
 		if strings.HasPrefix(match, "${") && strings.Contains(match, "}") {
@@ -191,8 +202,8 @@ func SubstituteArgs(content string, args []string) string {
 		if strings.HasPrefix(match, "$") && !strings.HasPrefix(match, "${") {
 			suffix := match[1:]
 
-			// $@ or $ARGUMENTS
-			if suffix == "@" || suffix == "ARGUMENTS" {
+			// $@, $+, or $ARGUMENTS
+			if suffix == "@" || suffix == "+" || suffix == "ARGUMENTS" {
 				return strings.Join(args, " ")
 			}
 
@@ -266,6 +277,48 @@ func joinArgsRange(args []string, start, length int) string {
 	return strings.Join(args[start:end], " ")
 }
 
+// HasArgPlaceholders reports whether the template content contains any
+// argument placeholders ($1, $@, $ARGUMENTS, ${@:...}, etc.).
+// Placeholders inside fenced code blocks and inline code spans are ignored.
+func (t *PromptTemplate) HasArgPlaceholders() bool {
+	return argPlaceholder.MatchString(fences.StripCode(t.Content))
+}
+
+// RequiredArgs returns the number of positional arguments the template
+// expects. This is determined by the highest $N or ${N} placeholder found
+// in the content (1-indexed, so $2 means 2 args required). The $+
+// placeholder (required variadic) ensures at least 1. Optional wildcards
+// ($@, $ARGUMENTS) do not contribute to the count.
+func (t *PromptTemplate) RequiredArgs() int {
+	content := fences.StripCode(t.Content)
+	maxN := 0
+	hasRequiredVariadic := strings.Contains(content, "$+")
+	for _, match := range argPlaceholder.FindAllStringSubmatch(content, -1) {
+		// Group 1: ${N} format — the N value.
+		if match[1] != "" {
+			if n, err := strconv.Atoi(match[1]); err == nil && n > maxN {
+				maxN = n
+			}
+		}
+		// Group 2: ${N:M} format — the N value (start index).
+		if match[2] != "" {
+			if n, err := strconv.Atoi(match[2]); err == nil && n > maxN {
+				maxN = n
+			}
+		}
+		// Group 6: $N format (no braces) — the N value.
+		if match[6] != "" {
+			if n, err := strconv.Atoi(match[6]); err == nil && n > maxN {
+				maxN = n
+			}
+		}
+	}
+	if hasRequiredVariadic && maxN < 1 {
+		maxN = 1
+	}
+	return maxN
+}
+
 // Expand substitutes arguments into the template content and returns the result.
 // It first parses args from the input string, then substitutes them into the template.
 func (t *PromptTemplate) Expand(argsInput string) string {

internal/prompts/template_test.go

@@ -129,6 +129,48 @@ func TestSubstituteArgs(t *testing.T) {
 			args:     []string{},
 			expected: "Args: ",
 		},
+		{
+			name:     "$1 inside code block preserved",
+			content:  "Use $1 here\n```bash\necho $1\n```\ndone",
+			args:     []string{"foo"},
+			expected: "Use foo here\n```bash\necho $1\n```\ndone",
+		},
+		{
+			name:     "$@ inside code block preserved",
+			content:  "Run $@\n```\necho $@\n```\n",
+			args:     []string{"a", "b"},
+			expected: "Run a b\n```\necho $@\n```\n",
+		},
+		{
+			name:     "all placeholders inside code block",
+			content:  "Prompt\n```\n$1 $2 $@\n```\n",
+			args:     []string{"x"},
+			expected: "Prompt\n```\n$1 $2 $@\n```\n",
+		},
+		{
+			name:     "$1 inside inline code preserved",
+			content:  "Use `$1` here and $1 outside",
+			args:     []string{"foo"},
+			expected: "Use `$1` here and foo outside",
+		},
+		{
+			name:     "$+ required variadic",
+			content:  "Args: $+",
+			args:     []string{"a", "b", "c"},
+			expected: "Args: a b c",
+		},
+		{
+			name:     "$+ with empty args",
+			content:  "Args: $+",
+			args:     []string{},
+			expected: "Args: ",
+		},
+		{
+			name:     "all placeholders in inline code",
+			content:  "Use `$1` and `$@` for args",
+			args:     []string{"x"},
+			expected: "Use `$1` and `$@` for args",
+		},
 	}
 
 	for _, tt := range tests {
@@ -213,3 +255,78 @@ func TestPromptTemplateExpand(t *testing.T) {
 		})
 	}
 }
+
+func TestHasArgPlaceholders(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    bool
+	}{
+		{"no placeholders", "Just a plain prompt with no args", false},
+		{"$1 placeholder", "Create a $1 component", true},
+		{"$@ placeholder", "Run with args: $@", true},
+		{"$ARGUMENTS placeholder", "Features: $ARGUMENTS", true},
+		{"${1} placeholder", "Name: ${1}", true},
+		{"${ARGUMENTS} placeholder", "All: ${ARGUMENTS}", true},
+		{"${@:1} placeholder", "Rest: ${@:1}", true},
+		{"${@:1:2} placeholder", "Slice: ${@:1:2}", true},
+		{"dollar in text", "Cost is one hundred dollars", false},
+		{"empty content", "", false},
+		{"$1 inside code block only", "Prompt\n```\necho $1\n```\n", false},
+		{"$1 outside and inside code block", "Use $1 here\n```\necho $1\n```\n", true},
+		{"$@ inside code block only", "Prompt\n```bash\necho $@\n```\n", false},
+		{"$+ placeholder", "Run with args: $+", true},
+		{"$+ inside inline code only", "Use `$+` for required args", false},
+		{"$1 inside inline code only", "Use `$1` for positional args", false},
+		{"$1 outside and in inline code", "Create $1 (see `$1` syntax)", true},
+		{"$@ outside $1 in inline code", "Run $@ with `$1` syntax", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tpl := &PromptTemplate{Content: tt.content}
+			if got := tpl.HasArgPlaceholders(); got != tt.want {
+				t.Errorf("HasArgPlaceholders() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestRequiredArgs(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    int
+	}{
+		{"no placeholders", "Just a plain prompt", 0},
+		{"$1 only", "Create a $1 component", 1},
+		{"$1 and $2", "Create $1 with $2", 2},
+		{"$3 skipping $2", "Use $1 and $3", 3},
+		{"${1} braced", "Name: ${1}", 1},
+		{"${2} braced", "Name: ${1} Desc: ${2}", 2},
+		{"$@ only", "Run with: $@", 0},
+		{"$ARGUMENTS only", "Features: $ARGUMENTS", 0},
+		{"${ARGUMENTS} only", "All: ${ARGUMENTS}", 0},
+		{"$1 and $@", "Create $1 with extras: $@", 1},
+		{"${@:1} slice only", "Rest: ${@:1}", 0},
+		{"${@:1:2} slice only", "Slice: ${@:1:2}", 0},
+		{"mixed $1 $2 and $@", "Create $1 named $2: $@", 2},
+		{"empty content", "", 0},
+		{"$2 inside code block only", "Prompt\n```\n$1 $2\n```\n", 0},
+		{"$1 outside $2 inside code block", "Use $1\n```\n$2 inside\n```\n", 1},
+		{"$+ only", "Run with: $+", 1},
+		{"$+ and $2", "Create $2 with: $+", 2},
+		{"$+ inside inline code only", "Use `$+` for required args", 0},
+		{"$1 and $2 in inline code only", "Use `$1` and `$2` for args", 0},
+		{"$1 outside $2 in inline code", "Create $1 (see `$2`)", 1},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tpl := &PromptTemplate{Content: tt.content}
+			if got := tpl.RequiredArgs(); got != tt.want {
+				t.Errorf("RequiredArgs() = %d, want %d", got, tt.want)
+			}
+		})
+	}
+}

internal/session/compaction_test.go

@@ -0,0 +1,317 @@
+package session
+
+import (
+	"slices"
+	"testing"
+
+	"charm.land/fantasy"
+	"github.com/mark3labs/kit/internal/message"
+)
+
+// TestCompactionCreatesNewLeaf verifies that after compaction, the compaction
+// entry has no parent (creating a new root), and BuildContext returns only
+// the summary and kept messages, not the old compacted messages.
+func TestCompactionCreatesNewLeaf(t *testing.T) {
+	tm := InMemoryTreeSession("/test")
+
+	// Add some messages: M1, M2 (old, will be compacted), M3, M4 (kept)
+	msg1 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Message 1 - old"}}}
+	msg2 := message.Message{Role: message.RoleAssistant, Parts: []message.ContentPart{message.TextContent{Text: "Message 2 - old"}}}
+	msg3 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Message 3 - kept"}}}
+	msg4 := message.Message{Role: message.RoleAssistant, Parts: []message.ContentPart{message.TextContent{Text: "Message 4 - kept"}}}
+
+	_, _ = tm.AppendMessage(msg1)
+	_, _ = tm.AppendMessage(msg2)
+	id3, _ := tm.AppendMessage(msg3)
+	id4, _ := tm.AppendMessage(msg4)
+
+	// Verify initial state - all messages should be in context
+	messages, _, _ := tm.BuildContext()
+	if len(messages) != 4 {
+		t.Fatalf("expected 4 messages before compaction, got %d", len(messages))
+	}
+
+	// Verify entry IDs
+	entryIDs := tm.GetContextEntryIDs()
+	if len(entryIDs) != 4 {
+		t.Fatalf("expected 4 entry IDs before compaction, got %d", len(entryIDs))
+	}
+
+	// Now add a compaction entry, simulating that M3 is the first kept entry
+	summary := "Summary of old messages"
+	compactionID, err := tm.AppendCompaction(summary, id3, 1000, 500, 2, []string{}, []string{})
+	if err != nil {
+		t.Fatalf("failed to append compaction: %v", err)
+	}
+
+	// Verify the compaction entry has no parent (empty ParentID)
+	compactionEntry := tm.GetEntry(compactionID).(*CompactionEntry)
+	if compactionEntry.ParentID != "" {
+		t.Errorf("compaction entry should have no parent, got %q", compactionEntry.ParentID)
+	}
+
+	// Verify the leaf is now the compaction entry
+	if tm.GetLeafID() != compactionID {
+		t.Errorf("leaf should be compaction entry %q, got %q", compactionID, tm.GetLeafID())
+	}
+
+	// Now BuildContext should return: [summary] + [M3, M4]
+	messages, _, _ = tm.BuildContext()
+	if len(messages) != 3 {
+		t.Fatalf("expected 3 messages after compaction (summary + 2 kept), got %d", len(messages))
+	}
+
+	// First message should be the summary
+	if messages[0].Role != fantasy.MessageRoleSystem {
+		t.Errorf("first message should be system summary, got %s", messages[0].Role)
+	}
+	summaryText := messages[0].Content[0].(fantasy.TextPart).Text
+	if summaryText != "[Conversation summary — earlier messages were compacted]\n\n"+summary {
+		t.Errorf("unexpected summary text: %s", summaryText)
+	}
+
+	// Second message should be M3 (kept)
+	if messages[1].Role != fantasy.MessageRoleUser {
+		t.Errorf("second message should be user (M3), got %s", messages[1].Role)
+	}
+	m3Text := messages[1].Content[0].(fantasy.TextPart).Text
+	if m3Text != "Message 3 - kept" {
+		t.Errorf("unexpected M3 text: %s", m3Text)
+	}
+
+	// Third message should be M4 (kept)
+	if messages[2].Role != fantasy.MessageRoleAssistant {
+		t.Errorf("third message should be assistant (M4), got %s", messages[2].Role)
+	}
+	m4Text := messages[2].Content[0].(fantasy.TextPart).Text
+	if m4Text != "Message 4 - kept" {
+		t.Errorf("unexpected M4 text: %s", m4Text)
+	}
+
+	// Verify GetContextEntryIDs returns correct IDs
+	entryIDs = tm.GetContextEntryIDs()
+	if len(entryIDs) != 3 {
+		t.Fatalf("expected 3 entry IDs after compaction (empty for summary + 2 kept), got %d: %v", len(entryIDs), entryIDs)
+	}
+
+	// First entry ID should be empty (summary has no entry)
+	if entryIDs[0] != "" {
+		t.Errorf("first entry ID should be empty (summary), got %q", entryIDs[0])
+	}
+
+	// Second and third should be id3 and id4 (the kept messages)
+	if entryIDs[1] != id3 {
+		t.Errorf("second entry ID should be %q (M3), got %q", id3, entryIDs[1])
+	}
+	if entryIDs[2] != id4 {
+		t.Errorf("third entry ID should be %q (M4), got %q", id4, entryIDs[2])
+	}
+}
+
+// TestCompactionWithNewMessagesAfterCompaction verifies that messages appended
+// after compaction are correctly included in the context.
+func TestCompactionWithNewMessagesAfterCompaction(t *testing.T) {
+	tm := InMemoryTreeSession("/test")
+
+	// Add initial messages
+	msg1 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Message 1"}}}
+	msg2 := message.Message{Role: message.RoleAssistant, Parts: []message.ContentPart{message.TextContent{Text: "Message 2"}}}
+	msg3 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Message 3 - kept"}}}
+
+	_, _ = tm.AppendMessage(msg1)
+	_, _ = tm.AppendMessage(msg2)
+	id3, _ := tm.AppendMessage(msg3)
+
+	// Compact, keeping only M3
+	_, _ = tm.AppendCompaction("Summary", id3, 1000, 500, 2, []string{}, []string{})
+
+	// Add a new message after compaction
+	msg4 := message.Message{Role: message.RoleAssistant, Parts: []message.ContentPart{message.TextContent{Text: "Message 4 - after compaction"}}}
+	_, _ = tm.AppendMessage(msg4)
+
+	// BuildContext should return: [summary] + [M4 (new after compaction)] + [M3 (kept)]
+	messages, _, _ := tm.BuildContext()
+	if len(messages) != 3 {
+		t.Fatalf("expected 3 messages (summary + M4 + M3), got %d: %+v", len(messages), messages)
+	}
+
+	// Verify order: summary, M4 (new), M3 (kept)
+	if messages[0].Role != fantasy.MessageRoleSystem {
+		t.Errorf("first message should be summary, got %s", messages[0].Role)
+	}
+	if messages[1].Role != fantasy.MessageRoleAssistant {
+		t.Errorf("second message should be assistant (M4), got %s", messages[1].Role)
+	}
+	m4Text := messages[1].Content[0].(fantasy.TextPart).Text
+	if m4Text != "Message 4 - after compaction" {
+		t.Errorf("unexpected M4 text: %s", m4Text)
+	}
+	if messages[2].Role != fantasy.MessageRoleUser {
+		t.Errorf("third message should be user (M3), got %s", messages[2].Role)
+	}
+
+	// Verify that M1 is NOT in the context
+	for i, msg := range messages {
+		if msg.Role == fantasy.MessageRoleUser {
+			text := msg.Content[0].(fantasy.TextPart).Text
+			if text == "Message 1" {
+				t.Errorf("Message 1 (compacted) should not be in context at index %d", i)
+			}
+		}
+	}
+}
+
+// TestCompactionWithNoKeptMessages verifies compaction when all messages are compacted.
+func TestCompactionWithNoKeptMessages(t *testing.T) {
+	tm := InMemoryTreeSession("/test")
+
+	// Add messages that will all be compacted
+	msg1 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Message 1"}}}
+	msg2 := message.Message{Role: message.RoleAssistant, Parts: []message.ContentPart{message.TextContent{Text: "Message 2"}}}
+
+	if _, err := tm.AppendMessage(msg1); err != nil {
+		t.Fatalf("failed to append message: %v", err)
+	}
+	if _, err := tm.AppendMessage(msg2); err != nil {
+		t.Fatalf("failed to append message: %v", err)
+	}
+
+	// Compact with no kept messages (empty firstKeptEntryID)
+	summary := "All messages summarized"
+	compactionID, _ := tm.AppendCompaction(summary, "", 1000, 100, 2, []string{}, []string{})
+
+	// Verify the compaction entry has no parent
+	compactionEntry := tm.GetEntry(compactionID).(*CompactionEntry)
+	if compactionEntry.ParentID != "" {
+		t.Errorf("compaction entry should have no parent, got %q", compactionEntry.ParentID)
+	}
+
+	// BuildContext should return only the summary
+	messages, _, _ := tm.BuildContext()
+	if len(messages) != 1 {
+		t.Fatalf("expected 1 message (summary only), got %d: %+v", len(messages), messages)
+	}
+	if messages[0].Role != fantasy.MessageRoleSystem {
+		t.Errorf("message should be system summary, got %s", messages[0].Role)
+	}
+}
+
+// TestMultipleCompactions verifies that multiple compactions work correctly.
+func TestMultipleCompactions(t *testing.T) {
+	tm := InMemoryTreeSession("/test")
+
+	// First batch of messages
+	msg1 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Batch 1 - User"}}}
+	msg2 := message.Message{Role: message.RoleAssistant, Parts: []message.ContentPart{message.TextContent{Text: "Batch 1 - Assistant"}}}
+	id1, _ := tm.AppendMessage(msg1)
+	id2, _ := tm.AppendMessage(msg2)
+
+	// First compaction
+	_, _ = tm.AppendCompaction("Summary 1", id1, 1000, 500, 1, []string{}, []string{})
+
+	// Second batch
+	msg3 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Batch 2 - User"}}}
+	msg4 := message.Message{Role: message.RoleAssistant, Parts: []message.ContentPart{message.TextContent{Text: "Batch 2 - Assistant"}}}
+	id3, _ := tm.AppendMessage(msg3)
+	id4, _ := tm.AppendMessage(msg4)
+
+	// Second compaction (compacting the first compaction + batch 2)
+	// Note: id3 is the first kept entry, so id3 and id4 should be preserved
+	compactionID2, _ := tm.AppendCompaction("Summary 2", id3, 1000, 500, 3, []string{}, []string{})
+
+	// Verify second compaction has no parent
+	compactionEntry2 := tm.GetEntry(compactionID2).(*CompactionEntry)
+	if compactionEntry2.ParentID != "" {
+		t.Errorf("second compaction entry should have no parent, got %q", compactionEntry2.ParentID)
+	}
+
+	// Add final message
+	msg5 := message.Message{Role: message.RoleUser, Parts: []message.ContentPart{message.TextContent{Text: "Final message"}}}
+	id5, _ := tm.AppendMessage(msg5)
+
+	// BuildContext should include:
+	// - Summary 2 (from second compaction)
+	// - msg5 (final message)
+	// - msg3, msg4 (kept from second compaction)
+	// But NOT Summary 1 or msg1, msg2 (they're before the first kept entry of compaction 2)
+	messages, _, _ := tm.BuildContext()
+
+	// Should have: Summary 2 + msg5 + msg3 + msg4 = 4 messages
+	if len(messages) != 4 {
+		t.Fatalf("expected 4 messages (Summary 2 + msg5 + msg3 + msg4), got %d: %+v", len(messages), messages)
+	}
+
+	// First should be Summary 2
+	if messages[0].Role != fantasy.MessageRoleSystem {
+		t.Errorf("first message should be system (Summary 2), got %s", messages[0].Role)
+	}
+	summaryText := messages[0].Content[0].(fantasy.TextPart).Text
+	if summaryText != "[Conversation summary — earlier messages were compacted]\n\nSummary 2" {
+		t.Errorf("unexpected summary: %s", summaryText)
+	}
+
+	// Verify msg5 is included
+	foundFinal := false
+	for _, msg := range messages {
+		if msg.Role == fantasy.MessageRoleUser {
+			text := msg.Content[0].(fantasy.TextPart).Text
+			if text == "Final message" {
+				foundFinal = true
+				break
+			}
+		}
+	}
+	if !foundFinal {
+		t.Error("Final message (msg5) should be in context")
+	}
+
+	// Verify msg1, msg2 are NOT included (compacted by first compaction, then second)
+	for _, msg := range messages {
+		if msg.Role == fantasy.MessageRoleUser || msg.Role == fantasy.MessageRoleAssistant {
+			text := msg.Content[0].(fantasy.TextPart).Text
+			if text == "Batch 1 - User" || text == "Batch 1 - Assistant" {
+				t.Errorf("Batch 1 messages should not be in context, found: %s", text)
+			}
+		}
+	}
+
+	// Verify entry IDs
+	entryIDs := tm.GetContextEntryIDs()
+	if len(entryIDs) != 4 {
+		t.Fatalf("expected 4 entry IDs, got %d: %v", len(entryIDs), entryIDs)
+	}
+
+	// First should be empty (summary)
+	if entryIDs[0] != "" {
+		t.Errorf("first entry ID should be empty (summary), got %q", entryIDs[0])
+	}
+
+	// Check that id5 is in the list
+	if !slices.Contains(entryIDs, id5) {
+		t.Errorf("id5 (final message) should be in entry IDs, got %v", entryIDs)
+	}
+
+	// Verify id3 and id4 ARE in the list (they were kept)
+	foundID3, foundID4 := false, false
+	for _, id := range entryIDs {
+		if id == id3 {
+			foundID3 = true
+		}
+		if id == id4 {
+			foundID4 = true
+		}
+	}
+	if !foundID3 {
+		t.Errorf("id3 (kept message) should be in entry IDs, got %v", entryIDs)
+	}
+	if !foundID4 {
+		t.Errorf("id4 (kept message) should be in entry IDs, got %v", entryIDs)
+	}
+
+	// Verify id1 and id2 are NOT in the list (they were compacted away)
+	for _, id := range entryIDs {
+		if id == id1 || id == id2 {
+			t.Errorf("id1 or id2 (compacted) should not be in entry IDs, found %q in %v", id, entryIDs)
+		}
+	}
+}

internal/session/entry.go

@@ -24,6 +24,7 @@ const (
 	EntryTypeSessionInfo   EntryType = "session_info"
 	EntryTypeExtensionData EntryType = "extension_data"
 	EntryTypeCompaction    EntryType = "compaction"
+	EntryTypeSystemPrompt  EntryType = "system_prompt"
 )
 
 // CurrentVersion is the session format version for JSONL tree sessions.
@@ -117,6 +118,19 @@ type CompactionEntry struct {
 	ModifiedFiles    []string `json:"modified_files,omitempty"`
 }
 
+// SystemPromptEntry records the system prompt and model used for the session.
+// This is primarily for sharing/debugging to see what instructions were
+// active during the conversation. It does NOT participate in the tree
+// structure (no ParentID) and is not used when building LLM context.
+type SystemPromptEntry struct {
+	Type      EntryType `json:"type"`      // always "system_prompt"
+	ID        string    `json:"id"`        // unique entry ID
+	Timestamp time.Time `json:"timestamp"` // when captured
+	Content   string    `json:"content"`   // the system prompt text
+	Model     string    `json:"model"`     // the model used (e.g., "claude-sonnet-4-5")
+	Provider  string    `json:"provider"`  // the provider used (e.g., "anthropic")
+}
+
 // GenerateEntryID creates a unique entry identifier (16 hex chars).
 func GenerateEntryID() string {
 	bytes := make([]byte, 8)
@@ -217,6 +231,18 @@ func NewCompactionEntry(parentID, summary, firstKeptEntryID string, tokensBefore
 	}
 }
 
+// NewSystemPromptEntry creates a SystemPromptEntry.
+func NewSystemPromptEntry(content, model, provider string) *SystemPromptEntry {
+	return &SystemPromptEntry{
+		Type:      EntryTypeSystemPrompt,
+		ID:        GenerateEntryID(),
+		Timestamp: time.Now(),
+		Content:   content,
+		Model:     model,
+		Provider:  provider,
+	}
+}
+
 // --- JSONL marshaling helpers ---
 
 // MarshalEntry serializes any entry to a JSON line (no trailing newline).
@@ -295,6 +321,13 @@ func UnmarshalEntry(data []byte) (any, error) {
 		}
 		return &e, nil
 
+	case EntryTypeSystemPrompt:
+		var e SystemPromptEntry
+		if err := json.Unmarshal(data, &e); err != nil {
+			return nil, fmt.Errorf("failed to unmarshal system_prompt entry: %w", err)
+		}
+		return &e, nil
+
 	default:
 		return nil, fmt.Errorf("unknown entry type: %q", env.Type)
 	}

internal/session/entry_test.go

@@ -0,0 +1,113 @@
+package session
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestSystemPromptEntry(t *testing.T) {
+	// Test creation
+	content := "You are a helpful coding assistant."
+	model := "claude-sonnet-4-5"
+	provider := "anthropic"
+	entry := NewSystemPromptEntry(content, model, provider)
+
+	if entry.Type != EntryTypeSystemPrompt {
+		t.Errorf("Expected type %q, got %q", EntryTypeSystemPrompt, entry.Type)
+	}
+
+	if entry.Content != content {
+		t.Errorf("Expected content %q, got %q", content, entry.Content)
+	}
+
+	if entry.Model != model {
+		t.Errorf("Expected model %q, got %q", model, entry.Model)
+	}
+
+	if entry.Provider != provider {
+		t.Errorf("Expected provider %q, got %q", provider, entry.Provider)
+	}
+
+	if entry.ID == "" {
+		t.Error("Expected non-empty ID")
+	}
+
+	// Test marshaling
+	data, err := MarshalEntry(entry)
+	if err != nil {
+		t.Fatalf("Failed to marshal: %v", err)
+	}
+
+	// Test unmarshaling
+	unmarshaled, err := UnmarshalEntry(data)
+	if err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+
+	sysPrompt, ok := unmarshaled.(*SystemPromptEntry)
+	if !ok {
+		t.Fatalf("Expected *SystemPromptEntry, got %T", unmarshaled)
+	}
+
+	if sysPrompt.Type != EntryTypeSystemPrompt {
+		t.Errorf("Unmarshaled: expected type %q, got %q", EntryTypeSystemPrompt, sysPrompt.Type)
+	}
+
+	if sysPrompt.Content != content {
+		t.Errorf("Unmarshaled: expected content %q, got %q", content, sysPrompt.Content)
+	}
+
+	if sysPrompt.Model != model {
+		t.Errorf("Unmarshaled: expected model %q, got %q", model, sysPrompt.Model)
+	}
+
+	if sysPrompt.Provider != provider {
+		t.Errorf("Unmarshaled: expected provider %q, got %q", provider, sysPrompt.Provider)
+	}
+
+	if sysPrompt.ID != entry.ID {
+		t.Errorf("Unmarshaled: expected ID %q, got %q", entry.ID, sysPrompt.ID)
+	}
+}
+
+func TestSystemPromptEntryJSONStructure(t *testing.T) {
+	content := "Test system prompt content"
+	model := "gpt-4o"
+	provider := "openai"
+	entry := NewSystemPromptEntry(content, model, provider)
+
+	data, err := MarshalEntry(entry)
+	if err != nil {
+		t.Fatalf("Failed to marshal: %v", err)
+	}
+
+	// Verify JSON structure
+	var raw map[string]any
+	if err := json.Unmarshal(data, &raw); err != nil {
+		t.Fatalf("Failed to unmarshal to raw map: %v", err)
+	}
+
+	if raw["type"] != "system_prompt" {
+		t.Errorf("Expected type 'system_prompt', got %v", raw["type"])
+	}
+
+	if raw["content"] != content {
+		t.Errorf("Expected content %q, got %v", content, raw["content"])
+	}
+
+	if raw["model"] != model {
+		t.Errorf("Expected model %q, got %v", model, raw["model"])
+	}
+
+	if raw["provider"] != provider {
+		t.Errorf("Expected provider %q, got %v", provider, raw["provider"])
+	}
+
+	if raw["id"] == "" || raw["id"] == nil {
+		t.Error("Expected non-empty id field")
+	}
+
+	if raw["timestamp"] == "" || raw["timestamp"] == nil {
+		t.Error("Expected non-empty timestamp field")
+	}
+}

internal/session/tree_manager.go

@@ -114,6 +114,187 @@ func CreateTreeSession(cwd string) (*TreeManager, error) {
 	return tm, nil
 }
 
+// ForkToNewSession creates a new session file containing the history up to and
+// including the target entry ID. This matches Pi's /fork behavior: it creates
+// a completely new session file with a parent_session reference, copying all
+// entries from the root to the target point.
+func (tm *TreeManager) ForkToNewSession(cwd string, targetID string) (*TreeManager, error) {
+	tm.mu.RLock()
+	defer tm.mu.RUnlock()
+
+	// Get the branch from root to target (root-to-leaf order).
+	branch := tm.getBranchLocked(targetID)
+	if len(branch) == 0 {
+		return nil, fmt.Errorf("target entry %q not found", targetID)
+	}
+
+	// Create a new session file.
+	newTm, err := CreateTreeSession(cwd)
+	if err != nil {
+		return nil, err
+	}
+
+	// Set the parent session reference in the header.
+	newTm.header.ParentSession = tm.filePath
+	newTm.header.ParentSessionID = tm.header.ID
+
+	// Rewrite the header with the parent reference.
+	// We need to close and recreate the file to rewrite the header.
+	if err := newTm.file.Close(); err != nil {
+		return nil, fmt.Errorf("failed to close new session file: %w", err)
+	}
+
+	// Recreate the file and write the updated header.
+	f, err := os.Create(newTm.filePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to recreate session file: %w", err)
+	}
+	newTm.file = f
+
+	if err := newTm.writeEntry(&newTm.header); err != nil {
+		_ = f.Close()
+		return nil, fmt.Errorf("failed to write session header: %w", err)
+	}
+
+	// Copy entries from the branch to the new session.
+	// We need to remap IDs since the new session is independent.
+	idMap := make(map[string]string) // old ID -> new ID
+	var prevNewID string
+
+	for _, entry := range branch {
+		oldID := tm.EntryID(entry)
+		newID := GenerateEntryID()
+		idMap[oldID] = newID
+
+		// Create a copy of the entry with the new ID and remapped parent.
+		var newEntry any
+		switch e := entry.(type) {
+		case *MessageEntry:
+			newEntry = &MessageEntry{
+				Entry: Entry{
+					Type:      EntryTypeMessage,
+					ID:        newID,
+					ParentID:  prevNewID, // Chain sequentially in new session
+					Timestamp: e.Timestamp,
+				},
+				Role:     e.Role,
+				Parts:    e.Parts,
+				Model:    e.Model,
+				Provider: e.Provider,
+			}
+			// Copy label if present.
+			if label, ok := tm.labels[oldID]; ok {
+				newTm.labels[newID] = label
+			}
+
+		case *ModelChangeEntry:
+			newEntry = &ModelChangeEntry{
+				Entry: Entry{
+					Type:      EntryTypeModelChange,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				Provider: e.Provider,
+				ModelID:  e.ModelID,
+			}
+
+		case *LabelEntry:
+			// Remap the target ID if it's in our copied branch.
+			newTargetID := e.TargetID
+			if mapped, ok := idMap[e.TargetID]; ok {
+				newTargetID = mapped
+			}
+			newEntry = &LabelEntry{
+				Entry: Entry{
+					Type:      EntryTypeLabel,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				TargetID: newTargetID,
+				Label:    e.Label,
+			}
+
+		case *SessionInfoEntry:
+			newEntry = &SessionInfoEntry{
+				Entry: Entry{
+					Type:      EntryTypeSessionInfo,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				Name: e.Name,
+			}
+			newTm.sessionName = e.Name
+
+		case *ExtensionDataEntry:
+			newEntry = &ExtensionDataEntry{
+				Entry: Entry{
+					Type:      EntryTypeExtensionData,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				ExtType: e.ExtType,
+				Data:    e.Data,
+			}
+
+		case *BranchSummaryEntry:
+			// Remap the from ID if it's in our copied branch.
+			newFromID := e.FromID
+			if mapped, ok := idMap[e.FromID]; ok {
+				newFromID = mapped
+			}
+			newEntry = &BranchSummaryEntry{
+				Entry: Entry{
+					Type:      EntryTypeBranchSummary,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				FromID:  newFromID,
+				Summary: e.Summary,
+			}
+
+		case *CompactionEntry:
+			// Remap the first kept entry ID if it's in our copied branch.
+			newFirstKeptID := e.FirstKeptEntryID
+			if mapped, ok := idMap[e.FirstKeptEntryID]; ok {
+				newFirstKeptID = mapped
+			}
+			newEntry = &CompactionEntry{
+				Entry: Entry{
+					Type:      EntryTypeCompaction,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				Summary:          e.Summary,
+				FirstKeptEntryID: newFirstKeptID,
+				TokensBefore:     e.TokensBefore,
+				TokensAfter:      e.TokensAfter,
+				MessagesRemoved:  e.MessagesRemoved,
+				ReadFiles:        e.ReadFiles,
+				ModifiedFiles:    e.ModifiedFiles,
+			}
+		}
+
+		if newEntry != nil {
+			if err := newTm.appendAndPersist(newEntry); err != nil {
+				_ = f.Close()
+				return nil, fmt.Errorf("failed to copy entry: %w", err)
+			}
+			prevNewID = newID
+		}
+	}
+
+	// Set the leaf to the last entry in the new session.
+	newTm.leafID = prevNewID
+
+	return newTm, nil
+}
+
 // OpenTreeSession opens an existing JSONL session file.
 func OpenTreeSession(path string) (*TreeManager, error) {
 	data, err := os.ReadFile(path)
@@ -328,11 +509,19 @@ func (tm *TreeManager) AppendExtensionData(extType, data string) (string, error)
 // AppendCompaction adds a compaction entry to the tree. The entry records
 // the summary and the ID of the first entry that should be preserved in the
 // LLM context. Messages before that entry are replaced by the summary.
+//
+// The compaction entry becomes a new "root" for the post-compaction branch
+// with no parent (empty ParentID). This breaks the parent chain so that old
+// compacted messages are no longer traversed when building context. The kept
+// messages are explicitly collected via FirstKeptEntryID in BuildContext.
 func (tm *TreeManager) AppendCompaction(summary, firstKeptEntryID string, tokensBefore, tokensAfter, messagesRemoved int, readFiles, modifiedFiles []string) (string, error) {
 	tm.mu.Lock()
 	defer tm.mu.Unlock()
 
-	entry := NewCompactionEntry(tm.leafID, summary, firstKeptEntryID, tokensBefore, tokensAfter, messagesRemoved, readFiles, modifiedFiles)
+	// The compaction entry has no parent, making it a new "root" for the
+	// post-compaction branch. This ensures old compacted messages are not
+	// traversed when walking from the current leaf.
+	entry := NewCompactionEntry("", summary, firstKeptEntryID, tokensBefore, tokensAfter, messagesRemoved, readFiles, modifiedFiles)
 	if err := tm.appendAndPersist(entry); err != nil {
 		return "", err
 	}
@@ -502,14 +691,18 @@ func (tm *TreeManager) BuildContext() (messages []fantasy.Message, provider stri
 	// Find the last compaction entry on this branch — it determines
 	// which older messages are replaced by the summary.
 	var lastCompaction *CompactionEntry
+	var compactionIndex = -1
 	for i := len(branch) - 1; i >= 0; i-- {
 		if c, ok := branch[i].(*CompactionEntry); ok {
 			lastCompaction = c
+			compactionIndex = i
 			break
 		}
 	}
 
-	// If there is a compaction, inject the summary first.
+	// If there is a compaction, inject the summary first and collect
+	// the kept messages starting from FirstKeptEntryID (since the
+	// compaction entry's parent chain doesn't include them).
 	if lastCompaction != nil {
 		messages = append(messages, fantasy.Message{
 			Role: fantasy.MessageRoleSystem,
@@ -519,21 +712,104 @@ func (tm *TreeManager) BuildContext() (messages []fantasy.Message, provider stri
 				},
 			},
 		})
-	}
 
-	// Determine whether to skip entries (everything before firstKeptEntryID).
-	skipping := lastCompaction != nil
-	for _, entry := range branch {
-		// Once we reach the first kept entry, stop skipping.
-		if skipping {
-			entryID := tm.EntryID(entry)
-			if entryID == lastCompaction.FirstKeptEntryID {
-				skipping = false
-			} else {
+		// Collect entries from the compaction entry itself (at compactionIndex)
+		// and any entries before it in the branch (newer messages).
+		for i := compactionIndex; i < len(branch); i++ {
+			entry := branch[i]
+			switch e := entry.(type) {
+			case *MessageEntry:
+				msg, err := e.ToMessage()
+				if err != nil {
+					continue // skip malformed entries
+				}
+				msgs := msg.ToLLMMessages()
+				messages = append(messages, msgs...)
+
+			case *BranchSummaryEntry:
+				// Convert branch summary to a user message for context.
+				if e.Summary != "" {
+					messages = append(messages, fantasy.Message{
+						Role: fantasy.MessageRoleUser,
+						Content: []fantasy.MessagePart{
+							fantasy.TextPart{
+								Text: fmt.Sprintf("[Branch context: %s]", e.Summary),
+							},
+						},
+					})
+				}
+
+			case *ModelChangeEntry:
+				provider = e.Provider
+				modelID = e.ModelID
+
+			case *CompactionEntry:
+				// Already handled above (summary injected).
 				continue
 			}
 		}
 
+		// Now collect the kept messages starting from FirstKeptEntryID.
+		// These are not in the current branch because the compaction entry
+		// is parented to the first kept entry's parent, not the first kept entry.
+		// We iterate through entries in order (not using getBranchLocked) to avoid
+		// walking back to old compacted messages.
+		// We stop when we reach the compaction entry to avoid double-counting
+		// messages that were added after the compaction.
+		if lastCompaction.FirstKeptEntryID != "" {
+			found := false
+			for _, entry := range tm.entries {
+				entryID := tm.EntryID(entry)
+
+				// Skip entries until we reach the first kept entry.
+				if !found {
+					if entryID == lastCompaction.FirstKeptEntryID {
+						found = true
+					} else {
+						continue
+					}
+				}
+
+				// Stop when we reach the compaction entry itself.
+				// Messages after the compaction are collected from the branch walk above.
+				if entryID == lastCompaction.ID {
+					break
+				}
+
+				// Process this kept entry.
+				switch e := entry.(type) {
+				case *MessageEntry:
+					msg, err := e.ToMessage()
+					if err != nil {
+						continue
+					}
+					msgs := msg.ToLLMMessages()
+					messages = append(messages, msgs...)
+
+				case *BranchSummaryEntry:
+					if e.Summary != "" {
+						messages = append(messages, fantasy.Message{
+							Role: fantasy.MessageRoleUser,
+							Content: []fantasy.MessagePart{
+								fantasy.TextPart{
+									Text: fmt.Sprintf("[Branch context: %s]", e.Summary),
+								},
+							},
+						})
+					}
+
+				case *ModelChangeEntry:
+					provider = e.Provider
+					modelID = e.ModelID
+				}
+			}
+		}
+
+		return messages, provider, modelID
+	}
+
+	// No compaction - process the entire branch normally.
+	for _, entry := range branch {
 		switch e := entry.(type) {
 		case *MessageEntry:
 			msg, err := e.ToMessage()
@@ -559,10 +835,6 @@ func (tm *TreeManager) BuildContext() (messages []fantasy.Message, provider stri
 		case *ModelChangeEntry:
 			provider = e.Provider
 			modelID = e.ModelID
-
-		case *CompactionEntry:
-			// Already handled above (the last one on the branch).
-			continue
 		}
 	}
 
@@ -672,31 +944,92 @@ func (tm *TreeManager) GetContextEntryIDs() []string {
 
 	// Find the last compaction entry for skip logic.
 	var lastCompaction *CompactionEntry
+	var compactionIndex = -1
 	for i := len(branch) - 1; i >= 0; i-- {
 		if c, ok := branch[i].(*CompactionEntry); ok {
 			lastCompaction = c
+			compactionIndex = i
 			break
 		}
 	}
 
 	var ids []string
 
-	// If there's a compaction summary injected, it has no entry ID.
+	// If there's a compaction, we need to collect IDs from:
+	// 1. Entries after the compaction entry in the branch (newer messages)
+	// 2. Entries from FirstKeptEntryID onwards (kept messages)
 	if lastCompaction != nil {
-		ids = append(ids, "") // placeholder for the summary system message
-	}
+		// Placeholder for the summary system message (no entry ID).
+		ids = append(ids, "")
 
-	skipping := lastCompaction != nil
-	for _, entry := range branch {
-		if skipping {
-			entryID := tm.EntryID(entry)
-			if entryID == lastCompaction.FirstKeptEntryID {
-				skipping = false
-			} else {
-				continue
+		// Collect IDs from entries after the compaction entry (newer messages).
+		for i := compactionIndex + 1; i < len(branch); i++ {
+			entry := branch[i]
+			switch e := entry.(type) {
+			case *MessageEntry:
+				msg, err := e.ToMessage()
+				if err != nil {
+					continue
+				}
+				msgs := msg.ToLLMMessages()
+				for range msgs {
+					ids = append(ids, e.ID)
+				}
+
+			case *BranchSummaryEntry:
+				if e.Summary != "" {
+					ids = append(ids, e.ID)
+				}
 			}
 		}
 
+		// Collect IDs from the kept messages starting at FirstKeptEntryID.
+		// We iterate through entries in order (not using getBranchLocked) to avoid
+		// walking back to old compacted messages.
+		// We stop when we reach the compaction entry to avoid double-counting.
+		if lastCompaction.FirstKeptEntryID != "" {
+			found := false
+			for _, entry := range tm.entries {
+				entryID := tm.EntryID(entry)
+
+				// Skip entries until we reach the first kept entry.
+				if !found {
+					if entryID == lastCompaction.FirstKeptEntryID {
+						found = true
+					} else {
+						continue
+					}
+				}
+
+				// Stop when we reach the compaction entry itself.
+				if entryID == lastCompaction.ID {
+					break
+				}
+
+				switch e := entry.(type) {
+				case *MessageEntry:
+					msg, err := e.ToMessage()
+					if err != nil {
+						continue
+					}
+					msgs := msg.ToLLMMessages()
+					for range msgs {
+						ids = append(ids, e.ID)
+					}
+
+				case *BranchSummaryEntry:
+					if e.Summary != "" {
+						ids = append(ids, e.ID)
+					}
+				}
+			}
+		}
+
+		return ids
+	}
+
+	// No compaction - collect IDs from the entire branch.
+	for _, entry := range branch {
 		switch e := entry.(type) {
 		case *MessageEntry:
 			msg, err := e.ToMessage()
@@ -712,9 +1045,6 @@ func (tm *TreeManager) GetContextEntryIDs() []string {
 			if e.Summary != "" {
 				ids = append(ids, e.ID)
 			}
-
-		case *CompactionEntry:
-			continue
 		}
 	}
 

internal/tools/connection_pool.go

@@ -8,11 +8,11 @@ import (
 	"sync"
 	"time"
 
-	"charm.land/fantasy"
 	"github.com/mark3labs/kit/internal/config"
 	"github.com/mark3labs/mcp-go/client"
 	"github.com/mark3labs/mcp-go/client/transport"
 	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
 )
 
 // ConnectionPoolConfig defines configuration parameters for the MCP connection pool.
@@ -60,34 +60,38 @@ type MCPConnection struct {
 // creation, health monitoring, and cleanup. The pool runs background health checks
 // to proactively identify and remove unhealthy connections.
 type MCPConnectionPool struct {
-	connections map[string]*MCPConnection
-	config      *ConnectionPoolConfig
-	mu          sync.RWMutex
-	model       fantasy.LanguageModel
-	ctx         context.Context
-	cancel      context.CancelFunc
-	debug       bool
-	debugLogger DebugLogger
+	connections       map[string]*MCPConnection
+	config            *ConnectionPoolConfig
+	mu                sync.RWMutex
+	ctx               context.Context
+	cancel            context.CancelFunc
+	debug             bool
+	debugLogger       DebugLogger
+	oauthFlow         *OAuthFlowRunner
+	tokenStoreFactory TokenStoreFactory // custom factory for per-server token stores (nil = default FileTokenStore)
 }
 
 // NewMCPConnectionPool creates a new MCP connection pool with the specified configuration.
 // If config is nil, default configuration values will be used. The pool starts a background
 // goroutine for periodic health checks that runs until Close is called.
-// The model parameter is used for MCP servers that require sampling support.
 // Thread-safe for concurrent use immediately after creation.
-func NewMCPConnectionPool(config *ConnectionPoolConfig, model fantasy.LanguageModel, debug bool) *MCPConnectionPool {
+func NewMCPConnectionPool(config *ConnectionPoolConfig, debug bool, authHandler MCPAuthHandler, tokenStoreFactory TokenStoreFactory) *MCPConnectionPool {
 	if config == nil {
 		config = DefaultConnectionPoolConfig()
 	}
 
 	ctx, cancel := context.WithCancel(context.Background())
 	pool := &MCPConnectionPool{
-		connections: make(map[string]*MCPConnection),
-		config:      config,
-		model:       model,
-		ctx:         ctx,
-		cancel:      cancel,
-		debug:       debug,
+		connections:       make(map[string]*MCPConnection),
+		config:            config,
+		ctx:               ctx,
+		cancel:            cancel,
+		debug:             debug,
+		tokenStoreFactory: tokenStoreFactory,
+	}
+
+	if authHandler != nil {
+		pool.oauthFlow = NewOAuthFlowRunner(authHandler)
 	}
 
 	go pool.startHealthCheck()
@@ -103,6 +107,15 @@ func (p *MCPConnectionPool) SetDebugLogger(logger DebugLogger) {
 	p.debugLogger = logger
 }
 
+// SetOAuthFlow sets the OAuth flow runner for the connection pool.
+// When set, the pool can trigger OAuth re-authorization when a tool call fails
+// with an OAuth error (e.g. expired token). Thread-safe and can be called at any time.
+func (p *MCPConnectionPool) SetOAuthFlow(flow *OAuthFlowRunner) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.oauthFlow = flow
+}
+
 // GetConnection retrieves or creates a connection for the specified MCP server.
 // If a healthy, non-idle connection exists in the pool, it will be reused.
 // Otherwise, a new connection is created and added to the pool.
@@ -230,18 +243,43 @@ func (p *MCPConnectionPool) performHealthCheck(ctx context.Context, conn *MCPCon
 
 // createConnection creates a new connection
 func (p *MCPConnectionPool) createConnection(ctx context.Context, serverName string, serverConfig config.MCPServerConfig) (*MCPConnection, error) {
-	client, err := p.createMCPClient(ctx, serverName, serverConfig)
+	mcpClient, err := p.createMCPClient(ctx, serverName, serverConfig)
 	if err != nil {
-		return nil, err
+		// SSE transport can return OAuth error during Start()
+		if p.oauthFlow != nil && IsOAuthError(err) {
+			if flowErr := p.oauthFlow.RunAuthFlow(ctx, serverName, err); flowErr != nil {
+				return nil, fmt.Errorf("OAuth authorization failed: %w", flowErr)
+			}
+			// Retry after successful auth
+			mcpClient, err = p.createMCPClient(ctx, serverName, serverConfig)
+			if err != nil {
+				return nil, err
+			}
+		} else {
+			return nil, err
+		}
 	}
 
-	if err := p.initializeClient(ctx, client); err != nil {
-		_ = client.Close()
-		return nil, err
+	if err := p.initializeClient(ctx, mcpClient); err != nil {
+		// Streamable HTTP transport returns OAuth error during Initialize()
+		if p.oauthFlow != nil && IsOAuthError(err) {
+			if flowErr := p.oauthFlow.RunAuthFlow(ctx, serverName, err); flowErr != nil {
+				_ = mcpClient.Close()
+				return nil, fmt.Errorf("OAuth authorization failed: %w", flowErr)
+			}
+			// Retry initialization after successful auth
+			if err := p.initializeClient(ctx, mcpClient); err != nil {
+				_ = mcpClient.Close()
+				return nil, err
+			}
+		} else {
+			_ = mcpClient.Close()
+			return nil, err
+		}
 	}
 
 	conn := &MCPConnection{
-		client:       client,
+		client:       mcpClient,
 		serverName:   serverName,
 		serverConfig: serverConfig,
 		lastUsed:     time.Now(),
@@ -267,6 +305,8 @@ func (p *MCPConnectionPool) createMCPClient(ctx context.Context, serverName stri
 		return p.createSSEClient(ctx, serverConfig)
 	case "streamable":
 		return p.createStreamableClient(ctx, serverConfig)
+	case "inprocess":
+		return p.createInProcessClient(serverConfig)
 	default:
 		return nil, fmt.Errorf("unsupported transport type '%s' for server %s", transportType, serverName)
 	}
@@ -323,13 +363,39 @@ func (p *MCPConnectionPool) createSSEClient(ctx context.Context, serverConfig co
 		}
 	}
 
+	// Enable OAuth for remote transports when an auth handler is configured.
+	// The OAuthConfig uses PKCE and the handler's redirect URI. If the server
+	// config provides a pre-registered ClientID (for servers that don't support
+	// dynamic client registration, e.g. GitHub), it is passed through directly.
+	if p.oauthFlow != nil {
+		tokenStore, tsErr := p.createTokenStore(serverConfig.URL)
+		if tsErr != nil {
+			return nil, fmt.Errorf("failed to create token store: %w", tsErr)
+		}
+		oauthCfg := transport.OAuthConfig{
+			RedirectURI: p.oauthFlow.handler.RedirectURI(),
+			PKCEEnabled: true,
+			TokenStore:  tokenStore,
+		}
+		if serverConfig.OAuthClientID != "" {
+			oauthCfg.ClientID = serverConfig.OAuthClientID
+		}
+		if serverConfig.OAuthClientSecret != "" {
+			oauthCfg.ClientSecret = serverConfig.OAuthClientSecret
+		}
+		if len(serverConfig.OAuthScopes) > 0 {
+			oauthCfg.Scopes = serverConfig.OAuthScopes
+		}
+		options = append(options, transport.WithOAuth(oauthCfg))
+	}
+
 	sseClient, err := client.NewSSEMCPClient(serverConfig.URL, options...)
 	if err != nil {
 		return nil, err
 	}
 
 	if err := sseClient.Start(ctx); err != nil {
-		return nil, fmt.Errorf("failed to start SSE client: %v", err)
+		return nil, fmt.Errorf("failed to start SSE client: %w", err)
 	}
 
 	return sseClient, nil
@@ -354,18 +420,70 @@ func (p *MCPConnectionPool) createStreamableClient(ctx context.Context, serverCo
 		}
 	}
 
+	// Enable OAuth for remote transports when an auth handler is configured.
+	// The OAuthConfig uses PKCE and the handler's redirect URI. If the server
+	// config provides a pre-registered ClientID (for servers that don't support
+	// dynamic client registration, e.g. GitHub), it is passed through directly.
+	if p.oauthFlow != nil {
+		tokenStore, tsErr := p.createTokenStore(serverConfig.URL)
+		if tsErr != nil {
+			return nil, fmt.Errorf("failed to create token store: %w", tsErr)
+		}
+		oauthCfg := transport.OAuthConfig{
+			RedirectURI: p.oauthFlow.handler.RedirectURI(),
+			PKCEEnabled: true,
+			TokenStore:  tokenStore,
+		}
+		if serverConfig.OAuthClientID != "" {
+			oauthCfg.ClientID = serverConfig.OAuthClientID
+		}
+		if serverConfig.OAuthClientSecret != "" {
+			oauthCfg.ClientSecret = serverConfig.OAuthClientSecret
+		}
+		if len(serverConfig.OAuthScopes) > 0 {
+			oauthCfg.Scopes = serverConfig.OAuthScopes
+		}
+		options = append(options, transport.WithHTTPOAuth(oauthCfg))
+	}
+
 	streamableClient, err := client.NewStreamableHttpClient(serverConfig.URL, options...)
 	if err != nil {
 		return nil, err
 	}
 
 	if err := streamableClient.Start(ctx); err != nil {
-		return nil, fmt.Errorf("failed to start streamable HTTP client: %v", err)
+		return nil, fmt.Errorf("failed to start streamable HTTP client: %w", err)
 	}
 
 	return streamableClient, nil
 }
 
+// createInProcessClient creates an in-process MCP client that communicates
+// directly with an *server.MCPServer in the same process. No subprocess is
+// spawned and no network I/O occurs — calls go through JSON marshal →
+// MCPServer.HandleMessage → JSON unmarshal, all in-memory.
+func (p *MCPConnectionPool) createInProcessClient(serverConfig config.MCPServerConfig) (client.MCPClient, error) {
+	srv, ok := serverConfig.InProcessServer.(*server.MCPServer)
+	if !ok {
+		return nil, fmt.Errorf("InProcessServer must be *server.MCPServer, got %T", serverConfig.InProcessServer)
+	}
+	inProcessClient, err := client.NewInProcessClient(srv)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create in-process client: %w", err)
+	}
+	return inProcessClient, nil
+}
+
+// createTokenStore creates a token store for the given server URL.
+// If a custom TokenStoreFactory is configured, it is used; otherwise the
+// default file-backed token store is created.
+func (p *MCPConnectionPool) createTokenStore(serverURL string) (transport.TokenStore, error) {
+	if p.tokenStoreFactory != nil {
+		return p.tokenStoreFactory(serverURL)
+	}
+	return NewFileTokenStore(serverURL)
+}
+
 // initializeClient initializes the client
 func (p *MCPConnectionPool) initializeClient(ctx context.Context, client client.MCPClient) error {
 	initCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
@@ -381,7 +499,7 @@ func (p *MCPConnectionPool) initializeClient(ctx context.Context, client client.
 
 	_, err := client.Initialize(initCtx, initRequest)
 	if err != nil {
-		return fmt.Errorf("initialization timeout or failed: %v", err)
+		return fmt.Errorf("initialization timeout or failed: %w", err)
 	}
 
 	if p.debugLogger != nil && p.debugLogger.IsDebugEnabled() {
@@ -512,6 +630,27 @@ func (p *MCPConnectionPool) GetClients() map[string]client.MCPClient {
 	return clients
 }
 
+// RemoveConnection closes and removes a single connection from the pool.
+// Returns an error if the connection does not exist or if closing fails.
+// Thread-safe for concurrent use.
+func (p *MCPConnectionPool) RemoveConnection(serverName string) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	conn, exists := p.connections[serverName]
+	if !exists {
+		return fmt.Errorf("connection %q not found in pool", serverName)
+	}
+
+	err := conn.client.Close()
+	delete(p.connections, serverName)
+
+	if p.debugLogger != nil && p.debugLogger.IsDebugEnabled() {
+		p.debugLogger.LogDebug(fmt.Sprintf("[POOL] Removed connection %s", serverName))
+	}
+	return err
+}
+
 // Close gracefully shuts down the connection pool, closing all client connections
 // and stopping the background health check goroutine. It attempts to close all
 // connections even if some fail, logging any errors encountered.
@@ -539,6 +678,9 @@ func (p *MCPConnectionPool) Close() error {
 
 // isConnectionError checks if the error is connection-related
 func isConnectionError(err error) bool {
+	if IsOAuthError(err) {
+		return false // OAuth errors are recoverable, not connection failures
+	}
 	errStr := err.Error()
 	return strings.Contains(errStr, "Connection not found") ||
 		strings.Contains(errStr, "transport error") ||

internal/tools/fantasy_adapter.go

@@ -1,88 +0,0 @@
-package tools
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-
-	"charm.land/fantasy"
-	"github.com/mark3labs/mcp-go/mcp"
-)
-
-// mcpFantasyTool adapts an MCP tool to the fantasy.AgentTool interface.
-// It bridges the MCP tool protocol with fantasy's agent tool system, handling
-// name prefixing, schema conversion, connection pooling, and result marshaling.
-type mcpFantasyTool struct {
-	toolInfo        fantasy.ToolInfo
-	mapping         *toolMapping
-	providerOptions fantasy.ProviderOptions
-}
-
-// Info returns the fantasy tool info including name, description, and parameter schema.
-func (t *mcpFantasyTool) Info() fantasy.ToolInfo {
-	return t.toolInfo
-}
-
-// Run executes the MCP tool by routing through the connection pool.
-// It maps the prefixed tool name back to the original name, retrieves a healthy
-// connection, invokes the tool, and converts the MCP result to a fantasy ToolResponse.
-func (t *mcpFantasyTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
-	// Parse and validate JSON arguments
-	var arguments any
-	input := call.Input
-	if input == "" || input == "{}" {
-		arguments = nil
-	} else {
-		var temp any
-		if err := json.Unmarshal([]byte(input), &temp); err != nil {
-			return fantasy.NewTextErrorResponse(fmt.Sprintf("invalid JSON arguments: %v", err)), nil
-		}
-		arguments = json.RawMessage(input)
-	}
-
-	// Get connection from pool with health check
-	conn, err := t.mapping.manager.connectionPool.GetConnectionWithHealthCheck(
-		ctx, t.mapping.serverName, t.mapping.serverConfig,
-	)
-	if err != nil {
-		return fantasy.ToolResponse{}, fmt.Errorf("failed to get healthy connection from pool: %w", err)
-	}
-
-	// Call the MCP tool using the original (unprefixed) name
-	result, err := conn.client.CallTool(ctx, mcp.CallToolRequest{
-		Request: mcp.Request{
-			Method: "tools/call",
-		},
-		Params: mcp.CallToolParams{
-			Name:      t.mapping.originalName,
-			Arguments: arguments,
-		},
-	})
-	if err != nil {
-		// Mark connection as unhealthy for automatic recovery
-		t.mapping.manager.connectionPool.HandleConnectionError(t.mapping.serverName, err)
-		return fantasy.ToolResponse{}, fmt.Errorf("failed to call mcp tool: %w", err)
-	}
-
-	// Marshal the MCP result to JSON string
-	marshaledResult, err := json.Marshal(result)
-	if err != nil {
-		return fantasy.ToolResponse{}, fmt.Errorf("failed to marshal mcp tool result: %w", err)
-	}
-
-	// Return as text response, preserving error status from MCP
-	if result.IsError {
-		return fantasy.NewTextErrorResponse(string(marshaledResult)), nil
-	}
-	return fantasy.NewTextResponse(string(marshaledResult)), nil
-}
-
-// ProviderOptions returns provider-specific options for this tool.
-func (t *mcpFantasyTool) ProviderOptions() fantasy.ProviderOptions {
-	return t.providerOptions
-}
-
-// SetProviderOptions sets provider-specific options for this tool.
-func (t *mcpFantasyTool) SetProviderOptions(opts fantasy.ProviderOptions) {
-	t.providerOptions = opts
-}

internal/tools/inprocess_test.go

@@ -0,0 +1,244 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/mark3labs/kit/internal/config"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+// newTestInProcessServer creates a simple MCP server with one tool for testing.
+func newTestInProcessServer() *server.MCPServer {
+	srv := server.NewMCPServer("test-server", "1.0.0",
+		server.WithToolCapabilities(true),
+	)
+	srv.AddTool(
+		mcp.NewTool("greet",
+			mcp.WithDescription("Say hello"),
+			mcp.WithString("name", mcp.Required(), mcp.Description("Name to greet")),
+		),
+		func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			name, _ := req.GetArguments()["name"].(string)
+			return mcp.NewToolResultText("Hello, " + name + "!"), nil
+		},
+	)
+	return srv
+}
+
+func TestInProcessTransportType(t *testing.T) {
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: newTestInProcessServer(),
+	}
+	if got := cfg.GetTransportType(); got != "inprocess" {
+		t.Errorf("GetTransportType() = %q, want %q", got, "inprocess")
+	}
+}
+
+func TestInProcessTransportTypeInferred(t *testing.T) {
+	// When Type is empty but InProcessServer is set, infer "inprocess".
+	cfg := config.MCPServerConfig{
+		InProcessServer: newTestInProcessServer(),
+	}
+	if got := cfg.GetTransportType(); got != "inprocess" {
+		t.Errorf("GetTransportType() = %q, want %q", got, "inprocess")
+	}
+}
+
+func TestInProcessValidation(t *testing.T) {
+	// Valid: InProcessServer is set.
+	validCfg := &config.Config{
+		MCPServers: map[string]config.MCPServerConfig{
+			"test": {
+				Type:            "inprocess",
+				InProcessServer: newTestInProcessServer(),
+			},
+		},
+	}
+	if err := validCfg.Validate(); err != nil {
+		t.Errorf("expected valid config, got error: %v", err)
+	}
+
+	// Invalid: type is inprocess but InProcessServer is nil.
+	invalidCfg := &config.Config{
+		MCPServers: map[string]config.MCPServerConfig{
+			"test": {
+				Type: "inprocess",
+			},
+		},
+	}
+	if err := invalidCfg.Validate(); err == nil {
+		t.Error("expected validation error for nil InProcessServer, got nil")
+	}
+}
+
+func TestConnectionPoolInProcessClient(t *testing.T) {
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	defer func() { _ = pool.Close() }()
+
+	ctx := context.Background()
+	srv := newTestInProcessServer()
+
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: srv,
+	}
+
+	conn, err := pool.GetConnection(ctx, "test-inproc", cfg)
+	if err != nil {
+		t.Fatalf("GetConnection failed: %v", err)
+	}
+
+	// Verify the connection is healthy and functional.
+	if !conn.isHealthy {
+		t.Error("expected connection to be healthy")
+	}
+
+	// List tools to verify the connection works end-to-end.
+	toolsResp, err := conn.client.ListTools(ctx, mcp.ListToolsRequest{})
+	if err != nil {
+		t.Fatalf("ListTools failed: %v", err)
+	}
+	if len(toolsResp.Tools) != 1 {
+		t.Fatalf("expected 1 tool, got %d", len(toolsResp.Tools))
+	}
+	if toolsResp.Tools[0].Name != "greet" {
+		t.Errorf("expected tool name 'greet', got %q", toolsResp.Tools[0].Name)
+	}
+}
+
+func TestConnectionPoolInProcessToolExecution(t *testing.T) {
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	defer func() { _ = pool.Close() }()
+
+	ctx := context.Background()
+	srv := newTestInProcessServer()
+
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: srv,
+	}
+
+	conn, err := pool.GetConnection(ctx, "test-inproc", cfg)
+	if err != nil {
+		t.Fatalf("GetConnection failed: %v", err)
+	}
+
+	// Call the tool.
+	result, err := conn.client.CallTool(ctx, mcp.CallToolRequest{
+		Request: mcp.Request{Method: "tools/call"},
+		Params: mcp.CallToolParams{
+			Name:      "greet",
+			Arguments: map[string]any{"name": "World"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("CallTool failed: %v", err)
+	}
+	if result.IsError {
+		t.Error("expected non-error result")
+	}
+	if len(result.Content) == 0 {
+		t.Fatal("expected at least one content block")
+	}
+	text, ok := result.Content[0].(mcp.TextContent)
+	if !ok {
+		t.Fatalf("expected TextContent, got %T", result.Content[0])
+	}
+	if text.Text != "Hello, World!" {
+		t.Errorf("expected 'Hello, World!', got %q", text.Text)
+	}
+}
+
+func TestMCPToolManagerInProcess(t *testing.T) {
+	ctx := context.Background()
+	srv := newTestInProcessServer()
+
+	mgr := NewMCPToolManager()
+
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: srv,
+	}
+
+	count, err := mgr.AddServer(ctx, "myserver", cfg)
+	if err != nil {
+		t.Fatalf("AddServer failed: %v", err)
+	}
+	if count != 1 {
+		t.Errorf("expected 1 tool, got %d", count)
+	}
+
+	tools := mgr.GetTools()
+	if len(tools) != 1 {
+		t.Fatalf("expected 1 tool, got %d", len(tools))
+	}
+	if tools[0].Name != "myserver__greet" {
+		t.Errorf("expected tool name 'myserver__greet', got %q", tools[0].Name)
+	}
+
+	// Execute the tool.
+	input, _ := json.Marshal(map[string]any{"name": "SDK"})
+	result, err := mgr.ExecuteTool(ctx, "myserver__greet", string(input))
+	if err != nil {
+		t.Fatalf("ExecuteTool failed: %v", err)
+	}
+	if result.IsError {
+		t.Error("expected non-error result")
+	}
+	if result.Content == "" {
+		t.Error("expected non-empty result content")
+	}
+
+	// Verify result contains our greeting.
+	if !strings.Contains(result.Content, "Hello, SDK!") {
+		t.Errorf("expected 'Hello, SDK!' in result, got %q", result.Content)
+	}
+}
+
+func TestConnectionPoolInProcessInvalidServer(t *testing.T) {
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	defer func() { _ = pool.Close() }()
+
+	ctx := context.Background()
+
+	// Pass a non-*server.MCPServer value.
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: "not a server",
+	}
+
+	_, err := pool.GetConnection(ctx, "bad", cfg)
+	if err == nil {
+		t.Fatal("expected error for invalid InProcessServer type")
+	}
+}
+
+func TestConnectionPoolInProcessReuse(t *testing.T) {
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	defer func() { _ = pool.Close() }()
+
+	ctx := context.Background()
+	srv := newTestInProcessServer()
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: srv,
+	}
+
+	// Get connection twice — should reuse.
+	conn1, err := pool.GetConnection(ctx, "reuse-test", cfg)
+	if err != nil {
+		t.Fatalf("first GetConnection failed: %v", err)
+	}
+	conn2, err := pool.GetConnection(ctx, "reuse-test", cfg)
+	if err != nil {
+		t.Fatalf("second GetConnection failed: %v", err)
+	}
+	if conn1 != conn2 {
+		t.Error("expected same connection object on reuse")
+	}
+}

internal/tools/mcp_dynamic_integration_test.go

@@ -0,0 +1,323 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/mark3labs/kit/internal/config"
+)
+
+// testdataDir returns the absolute path to the testdata directory.
+func testdataDir(t *testing.T) string {
+	t.Helper()
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("cannot determine test file path")
+	}
+	return filepath.Join(filepath.Dir(file), "testdata")
+}
+
+// echoServerConfig returns an MCPServerConfig for the test echo MCP server.
+func echoServerConfig(t *testing.T) config.MCPServerConfig {
+	t.Helper()
+	script := filepath.Join(testdataDir(t), "echo_server.py")
+	if _, err := os.Stat(script); err != nil {
+		t.Skipf("echo_server.py not found: %v", err)
+	}
+	return config.MCPServerConfig{
+		Command: []string{"python3", script},
+	}
+}
+
+// TestMCPToolManager_AddServer_Integration tests adding a real MCP server
+// at runtime and verifying tools are loaded.
+func TestMCPToolManager_AddServer_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	manager := NewMCPToolManager()
+	defer func() { _ = manager.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Track callbacks.
+	var mu sync.Mutex
+	var loadedServer string
+	var loadedCount int
+	toolsChangedCount := 0
+
+	manager.SetOnServerLoaded(func(name string, count int, err error) {
+		mu.Lock()
+		loadedServer = name
+		loadedCount = count
+		mu.Unlock()
+	})
+	manager.SetOnToolsChanged(func() {
+		mu.Lock()
+		toolsChangedCount++
+		mu.Unlock()
+	})
+
+	// Add the server.
+	count, err := manager.AddServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("AddServer failed: %v", err)
+	}
+
+	if count != 2 {
+		t.Errorf("Expected 2 tools from echo server, got %d", count)
+	}
+
+	// Verify callbacks fired.
+	mu.Lock()
+	if loadedServer != "echo" {
+		t.Errorf("Expected onServerLoaded for 'echo', got %q", loadedServer)
+	}
+	if loadedCount != 2 {
+		t.Errorf("Expected onServerLoaded count=2, got %d", loadedCount)
+	}
+	if toolsChangedCount != 1 {
+		t.Errorf("Expected onToolsChanged called once, got %d", toolsChangedCount)
+	}
+	mu.Unlock()
+
+	// Verify tools are accessible.
+	tools := manager.GetTools()
+	if len(tools) != 2 {
+		t.Fatalf("Expected 2 tools, got %d", len(tools))
+	}
+
+	// Verify tool names are prefixed.
+	toolNames := make(map[string]bool)
+	for _, tool := range tools {
+		toolNames[tool.Name] = true
+	}
+	if !toolNames["echo__echo"] {
+		t.Error("Expected tool 'echo__echo'")
+	}
+	if !toolNames["echo__greet"] {
+		t.Error("Expected tool 'echo__greet'")
+	}
+
+	// Verify server appears in loaded names.
+	names := manager.GetLoadedServerNames()
+	if !slices.Contains(names, "echo") {
+		t.Errorf("Expected 'echo' in loaded server names, got: %v", names)
+	}
+}
+
+// TestMCPToolManager_RemoveServer_Integration tests removing a real MCP server
+// and verifying tools are cleaned up.
+func TestMCPToolManager_RemoveServer_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	manager := NewMCPToolManager()
+	defer func() { _ = manager.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Add the server first.
+	count, err := manager.AddServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("AddServer failed: %v", err)
+	}
+	if count != 2 {
+		t.Fatalf("Expected 2 tools, got %d", count)
+	}
+
+	var mu sync.Mutex
+	toolsChangedCount := 0
+	manager.SetOnToolsChanged(func() {
+		mu.Lock()
+		toolsChangedCount++
+		mu.Unlock()
+	})
+
+	// Remove the server.
+	err = manager.RemoveServer("echo")
+	if err != nil {
+		t.Fatalf("RemoveServer failed: %v", err)
+	}
+
+	// Verify tools are gone.
+	tools := manager.GetTools()
+	if len(tools) != 0 {
+		t.Errorf("Expected 0 tools after removal, got %d", len(tools))
+	}
+
+	// Verify callback fired.
+	mu.Lock()
+	if toolsChangedCount != 1 {
+		t.Errorf("Expected onToolsChanged called once, got %d", toolsChangedCount)
+	}
+	mu.Unlock()
+
+	// Verify server is gone from loaded names.
+	names := manager.GetLoadedServerNames()
+	for _, n := range names {
+		if n == "echo" {
+			t.Error("Server 'echo' should not appear in loaded names after removal")
+		}
+	}
+
+	// Removing again should error.
+	err = manager.RemoveServer("echo")
+	if err == nil {
+		t.Fatal("Expected error removing already-removed server")
+	}
+	if !strings.Contains(err.Error(), "not loaded") {
+		t.Errorf("Expected 'not loaded' error, got: %v", err)
+	}
+}
+
+// TestMCPToolManager_AddRemoveMultiple_Integration tests adding and removing
+// multiple servers, verifying tool isolation.
+func TestMCPToolManager_AddRemoveMultiple_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	manager := NewMCPToolManager()
+	defer func() { _ = manager.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Add two servers with the same binary but different names.
+	count1, err := manager.AddServer(ctx, "server-a", cfg)
+	if err != nil {
+		t.Fatalf("AddServer server-a failed: %v", err)
+	}
+	count2, err := manager.AddServer(ctx, "server-b", cfg)
+	if err != nil {
+		t.Fatalf("AddServer server-b failed: %v", err)
+	}
+
+	totalTools := count1 + count2
+	if totalTools != 4 {
+		t.Fatalf("Expected 4 total tools (2+2), got %d", totalTools)
+	}
+
+	tools := manager.GetTools()
+	if len(tools) != 4 {
+		t.Fatalf("Expected 4 tools, got %d", len(tools))
+	}
+
+	// Remove server-a, verify server-b tools remain.
+	err = manager.RemoveServer("server-a")
+	if err != nil {
+		t.Fatalf("RemoveServer server-a failed: %v", err)
+	}
+
+	tools = manager.GetTools()
+	if len(tools) != 2 {
+		t.Fatalf("Expected 2 tools after removing server-a, got %d", len(tools))
+	}
+
+	// Remaining tools should all be from server-b.
+	for _, tool := range tools {
+		if !strings.HasPrefix(tool.Name, "server-b__") {
+			t.Errorf("Expected tool from server-b, got: %s", tool.Name)
+		}
+	}
+
+	// Remove server-b.
+	err = manager.RemoveServer("server-b")
+	if err != nil {
+		t.Fatalf("RemoveServer server-b failed: %v", err)
+	}
+
+	tools = manager.GetTools()
+	if len(tools) != 0 {
+		t.Errorf("Expected 0 tools after removing all servers, got %d", len(tools))
+	}
+}
+
+// TestMCPToolManager_AddServer_DuplicateDetection_Integration tests that
+// adding a server with the same name as an already loaded server errors.
+func TestMCPToolManager_AddServer_DuplicateDetection_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	manager := NewMCPToolManager()
+	defer func() { _ = manager.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Add the server.
+	_, err := manager.AddServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("First AddServer failed: %v", err)
+	}
+
+	// Try to add again with the same name.
+	_, err = manager.AddServer(ctx, "echo", cfg)
+	if err == nil {
+		t.Fatal("Expected error adding duplicate server")
+	}
+	if !strings.Contains(err.Error(), "already loaded") {
+		t.Errorf("Expected 'already loaded' error, got: %v", err)
+	}
+}
+
+// TestMCPToolManager_AddAfterRemove_Integration tests that a server can be
+// re-added after being removed.
+func TestMCPToolManager_AddAfterRemove_Integration(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping integration test in short mode")
+	}
+
+	manager := NewMCPToolManager()
+	defer func() { _ = manager.Close() }()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	cfg := echoServerConfig(t)
+
+	// Add, remove, re-add.
+	_, err := manager.AddServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("First AddServer failed: %v", err)
+	}
+
+	err = manager.RemoveServer("echo")
+	if err != nil {
+		t.Fatalf("RemoveServer failed: %v", err)
+	}
+
+	count, err := manager.AddServer(ctx, "echo", cfg)
+	if err != nil {
+		t.Fatalf("Re-AddServer failed: %v", err)
+	}
+	if count != 2 {
+		t.Errorf("Expected 2 tools on re-add, got %d", count)
+	}
+
+	tools := manager.GetTools()
+	if len(tools) != 2 {
+		t.Errorf("Expected 2 tools after re-add, got %d", len(tools))
+	}
+}

internal/tools/mcp_dynamic_test.go

@@ -0,0 +1,155 @@
+package tools
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/mark3labs/kit/internal/config"
+)
+
+// TestMCPToolManager_AddServer_DuplicateName verifies that adding a server
+// with a name that already exists returns an error.
+func TestMCPToolManager_AddServer_DuplicateName(t *testing.T) {
+	manager := NewMCPToolManager()
+
+	cfg := config.MCPServerConfig{
+		Command: []string{"non-existent-command"},
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// First add will fail (bad command), but let's test the duplicate detection
+	// by simulating a loaded server via LoadTools first.
+	loadCfg := &config.Config{
+		MCPServers: map[string]config.MCPServerConfig{
+			"test-server": cfg,
+		},
+	}
+	// This will fail to load but creates the connection pool.
+	_ = manager.LoadTools(ctx, loadCfg)
+
+	// Now try to add the same server name — the tools didn't load (bad command),
+	// so AddServer should not find a duplicate and should fail with connection error.
+	_, err := manager.AddServer(ctx, "test-server", cfg)
+	if err == nil {
+		t.Fatal("Expected error when adding server with bad command, got nil")
+	}
+	// It should be a connection error, not a duplicate error.
+	if strings.Contains(err.Error(), "already loaded") {
+		t.Fatalf("Should not report duplicate since server failed to load initially: %v", err)
+	}
+}
+
+// TestMCPToolManager_RemoveServer_NotLoaded verifies that removing a server
+// that doesn't exist returns an appropriate error.
+func TestMCPToolManager_RemoveServer_NotLoaded(t *testing.T) {
+	manager := NewMCPToolManager()
+
+	err := manager.RemoveServer("nonexistent")
+	if err == nil {
+		t.Fatal("Expected error when removing non-existent server, got nil")
+	}
+	if !strings.Contains(err.Error(), "not loaded") {
+		t.Errorf("Expected 'not loaded' error, got: %v", err)
+	}
+}
+
+// TestMCPToolManager_AddServer_CreatesConnectionPool verifies that AddServer
+// lazily creates a connection pool when LoadTools was never called.
+func TestMCPToolManager_AddServer_CreatesConnectionPool(t *testing.T) {
+	manager := NewMCPToolManager()
+
+	// Connection pool should be nil initially.
+	if manager.connectionPool != nil {
+		t.Fatal("Expected nil connection pool before any operation")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// AddServer with a bad command — should fail, but the pool should be created.
+	_, err := manager.AddServer(ctx, "lazy-server", config.MCPServerConfig{
+		Command: []string{"non-existent-command"},
+	})
+	if err == nil {
+		t.Fatal("Expected error for bad command")
+	}
+
+	// Connection pool should have been created.
+	if manager.connectionPool == nil {
+		t.Fatal("Expected connection pool to be created lazily by AddServer")
+	}
+}
+
+// TestMCPToolManager_OnToolsChanged_Callback verifies that the onToolsChanged
+// callback fires on RemoveServer (we can't easily test AddServer with a real
+// MCP server, but we can test the callback wiring).
+func TestMCPToolManager_OnToolsChanged_Callback(t *testing.T) {
+	manager := NewMCPToolManager()
+
+	var mu sync.Mutex
+	callCount := 0
+	manager.SetOnToolsChanged(func() {
+		mu.Lock()
+		callCount++
+		mu.Unlock()
+	})
+
+	// RemoveServer on non-existent should NOT fire callback.
+	_ = manager.RemoveServer("nonexistent")
+
+	mu.Lock()
+	if callCount != 0 {
+		t.Errorf("Expected 0 callback calls for failed remove, got %d", callCount)
+	}
+	mu.Unlock()
+}
+
+// TestMCPToolManager_Close_NilPool verifies Close is safe when the connection
+// pool was never initialized.
+func TestMCPToolManager_Close_NilPool(t *testing.T) {
+	manager := NewMCPToolManager()
+	err := manager.Close()
+	if err != nil {
+		t.Fatalf("Expected nil error from Close with nil pool, got: %v", err)
+	}
+}
+
+// TestMCPConnectionPool_RemoveConnection_NotFound verifies that removing a
+// non-existent connection returns an error.
+func TestMCPConnectionPool_RemoveConnection_NotFound(t *testing.T) {
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	defer func() { _ = pool.Close() }()
+
+	err := pool.RemoveConnection("nonexistent")
+	if err == nil {
+		t.Fatal("Expected error for non-existent connection")
+	}
+	if !strings.Contains(err.Error(), "not found") {
+		t.Errorf("Expected 'not found' error, got: %v", err)
+	}
+}
+
+// TestMCPToolManager_EnsureConnectionPool_Idempotent verifies that
+// ensureConnectionPool doesn't recreate an existing pool.
+func TestMCPToolManager_EnsureConnectionPool_Idempotent(t *testing.T) {
+	manager := NewMCPToolManager()
+
+	// First call creates the pool.
+	manager.ensureConnectionPool()
+	pool1 := manager.connectionPool
+	if pool1 == nil {
+		t.Fatal("Expected pool to be created")
+	}
+
+	// Second call should be a no-op.
+	manager.ensureConnectionPool()
+	pool2 := manager.connectionPool
+	if pool1 != pool2 {
+		t.Fatal("Expected ensureConnectionPool to be idempotent")
+	}
+}

internal/tools/mcp_prompts_test.go

@@ -0,0 +1,691 @@
+package tools
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"strings"
+	"testing"
+
+	mcpclient "github.com/mark3labs/mcp-go/client"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+// newTestPromptServer creates an in-process MCP server with prompt capabilities
+// and the specified prompts + handlers. Returns an initialized MCPClient.
+func newTestPromptServer(t *testing.T, prompts ...server.ServerPrompt) mcpclient.MCPClient {
+	t.Helper()
+
+	mcpServer := server.NewMCPServer(
+		"test-prompt-server", "1.0.0",
+		server.WithPromptCapabilities(true),
+		server.WithToolCapabilities(true),
+	)
+
+	if len(prompts) > 0 {
+		mcpServer.AddPrompts(prompts...)
+	}
+
+	// Add a dummy tool so loadServerTools has something to list.
+	mcpServer.AddTool(
+		mcp.NewTool("noop", mcp.WithDescription("no-op tool")),
+		func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			return mcp.NewToolResultText("ok"), nil
+		},
+	)
+
+	client, err := mcpclient.NewInProcessClient(mcpServer)
+	if err != nil {
+		t.Fatalf("NewInProcessClient: %v", err)
+	}
+
+	ctx := context.Background()
+	if err := client.Start(ctx); err != nil {
+		t.Fatalf("client.Start: %v", err)
+	}
+
+	initReq := mcp.InitializeRequest{}
+	initReq.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
+	initReq.Params.ClientInfo = mcp.Implementation{Name: "test", Version: "1.0"}
+	if _, err := client.Initialize(ctx, initReq); err != nil {
+		t.Fatalf("client.Initialize: %v", err)
+	}
+
+	t.Cleanup(func() { _ = client.Close() })
+	return client
+}
+
+// injectClientIntoManager sets up an MCPToolManager with a pre-connected
+// in-process client, bypassing the normal connection pool flow.
+func injectClientIntoManager(t *testing.T, serverName string, client mcpclient.MCPClient) *MCPToolManager {
+	t.Helper()
+
+	m := NewMCPToolManager()
+
+	// Create a minimal connection pool and inject our client.
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	pool.mu.Lock()
+	pool.connections[serverName] = &MCPConnection{
+		client:     client,
+		serverName: serverName,
+		isHealthy:  true,
+	}
+	pool.mu.Unlock()
+	m.connectionPool = pool
+
+	return m
+}
+
+func TestLoadServerPrompts_Basic(t *testing.T) {
+	ctx := context.Background()
+
+	client := newTestPromptServer(t,
+		server.ServerPrompt{
+			Prompt: mcp.NewPrompt("review-pr",
+				mcp.WithPromptDescription("Review a pull request"),
+				mcp.WithArgument("pr_number",
+					mcp.ArgumentDescription("The PR number to review"),
+					mcp.RequiredArgument(),
+				),
+				mcp.WithArgument("focus",
+					mcp.ArgumentDescription("Area to focus on"),
+				),
+			),
+			Handler: func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+				prNum := req.Params.Arguments["pr_number"]
+				return &mcp.GetPromptResult{
+					Description: "PR review prompt",
+					Messages: []mcp.PromptMessage{
+						{
+							Role: mcp.RoleUser,
+							Content: mcp.TextContent{
+								Type: "text",
+								Text: fmt.Sprintf("Please review PR #%s", prNum),
+							},
+						},
+					},
+				}, nil
+			},
+		},
+		server.ServerPrompt{
+			Prompt: mcp.NewPrompt("explain-code",
+				mcp.WithPromptDescription("Explain a piece of code"),
+			),
+			Handler: func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+				return &mcp.GetPromptResult{
+					Messages: []mcp.PromptMessage{
+						{
+							Role: mcp.RoleUser,
+							Content: mcp.TextContent{
+								Type: "text",
+								Text: "Please explain the following code.",
+							},
+						},
+					},
+				}, nil
+			},
+		},
+	)
+
+	m := injectClientIntoManager(t, "github", client)
+
+	conn := &MCPConnection{
+		client:     client,
+		serverName: "github",
+		isHealthy:  true,
+	}
+	m.loadServerPrompts(ctx, "github", conn)
+
+	prompts := m.GetPrompts()
+	if len(prompts) != 2 {
+		t.Fatalf("expected 2 prompts, got %d", len(prompts))
+	}
+
+	// Find review-pr prompt.
+	var reviewPR *MCPPrompt
+	for i := range prompts {
+		if prompts[i].Name == "review-pr" {
+			reviewPR = &prompts[i]
+			break
+		}
+	}
+	if reviewPR == nil {
+		t.Fatal("review-pr prompt not found")
+	}
+	if reviewPR.Description != "Review a pull request" {
+		t.Errorf("unexpected description: %q", reviewPR.Description)
+	}
+	if reviewPR.ServerName != "github" {
+		t.Errorf("unexpected server name: %q", reviewPR.ServerName)
+	}
+	if len(reviewPR.Arguments) != 2 {
+		t.Fatalf("expected 2 arguments, got %d", len(reviewPR.Arguments))
+	}
+
+	// Verify argument metadata.
+	arg0 := reviewPR.Arguments[0]
+	if arg0.Name != "pr_number" {
+		t.Errorf("expected first arg name 'pr_number', got %q", arg0.Name)
+	}
+	if !arg0.Required {
+		t.Error("expected first arg to be required")
+	}
+	arg1 := reviewPR.Arguments[1]
+	if arg1.Name != "focus" {
+		t.Errorf("expected second arg name 'focus', got %q", arg1.Name)
+	}
+	if arg1.Required {
+		t.Error("expected second arg to be optional")
+	}
+}
+
+func TestGetPrompt_ExpandsWithArgs(t *testing.T) {
+	ctx := context.Background()
+
+	client := newTestPromptServer(t,
+		server.ServerPrompt{
+			Prompt: mcp.NewPrompt("greet",
+				mcp.WithPromptDescription("Greet someone"),
+				mcp.WithArgument("name", mcp.RequiredArgument()),
+			),
+			Handler: func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+				name := req.Params.Arguments["name"]
+				return &mcp.GetPromptResult{
+					Description: "Greeting",
+					Messages: []mcp.PromptMessage{
+						{
+							Role: mcp.RoleUser,
+							Content: mcp.TextContent{
+								Type: "text",
+								Text: fmt.Sprintf("Hello, %s!", name),
+							},
+						},
+					},
+				}, nil
+			},
+		},
+	)
+
+	m := injectClientIntoManager(t, "myserver", client)
+
+	result, err := m.GetPrompt(ctx, "myserver", "greet", map[string]string{"name": "World"})
+	if err != nil {
+		t.Fatalf("GetPrompt error: %v", err)
+	}
+	if result.Description != "Greeting" {
+		t.Errorf("unexpected description: %q", result.Description)
+	}
+	if len(result.Messages) != 1 {
+		t.Fatalf("expected 1 message, got %d", len(result.Messages))
+	}
+	if result.Messages[0].Role != "user" {
+		t.Errorf("unexpected role: %q", result.Messages[0].Role)
+	}
+	if result.Messages[0].Content != "Hello, World!" {
+		t.Errorf("unexpected content: %q", result.Messages[0].Content)
+	}
+}
+
+func TestGetPrompt_MultipleMessages(t *testing.T) {
+	ctx := context.Background()
+
+	client := newTestPromptServer(t,
+		server.ServerPrompt{
+			Prompt: mcp.NewPrompt("chat-starter"),
+			Handler: func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+				return &mcp.GetPromptResult{
+					Messages: []mcp.PromptMessage{
+						{
+							Role:    mcp.RoleUser,
+							Content: mcp.TextContent{Type: "text", Text: "What is Go?"},
+						},
+						{
+							Role:    mcp.RoleAssistant,
+							Content: mcp.TextContent{Type: "text", Text: "Go is a programming language."},
+						},
+						{
+							Role:    mcp.RoleUser,
+							Content: mcp.TextContent{Type: "text", Text: "Tell me more."},
+						},
+					},
+				}, nil
+			},
+		},
+	)
+
+	m := injectClientIntoManager(t, "server", client)
+
+	result, err := m.GetPrompt(ctx, "server", "chat-starter", nil)
+	if err != nil {
+		t.Fatalf("GetPrompt error: %v", err)
+	}
+	if len(result.Messages) != 3 {
+		t.Fatalf("expected 3 messages, got %d", len(result.Messages))
+	}
+	if result.Messages[0].Role != "user" {
+		t.Errorf("msg[0] role: got %q, want 'user'", result.Messages[0].Role)
+	}
+	if result.Messages[1].Role != "assistant" {
+		t.Errorf("msg[1] role: got %q, want 'assistant'", result.Messages[1].Role)
+	}
+	if result.Messages[2].Content != "Tell me more." {
+		t.Errorf("msg[2] content: got %q, want 'Tell me more.'", result.Messages[2].Content)
+	}
+}
+
+func TestGetPrompt_ServerNotFound(t *testing.T) {
+	m := NewMCPToolManager()
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	m.connectionPool = pool
+
+	_, err := m.GetPrompt(context.Background(), "nonexistent", "foo", nil)
+	if err == nil {
+		t.Fatal("expected error for nonexistent server")
+	}
+}
+
+func TestGetPrompt_NoPool(t *testing.T) {
+	m := NewMCPToolManager()
+
+	_, err := m.GetPrompt(context.Background(), "any", "foo", nil)
+	if err == nil {
+		t.Fatal("expected error with no pool")
+	}
+}
+
+func TestRemoveServer_RemovesPrompts(t *testing.T) {
+	ctx := context.Background()
+
+	client := newTestPromptServer(t,
+		server.ServerPrompt{
+			Prompt: mcp.NewPrompt("my-prompt",
+				mcp.WithPromptDescription("A test prompt"),
+			),
+			Handler: func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+				return &mcp.GetPromptResult{
+					Messages: []mcp.PromptMessage{
+						{Role: mcp.RoleUser, Content: mcp.TextContent{Type: "text", Text: "hi"}},
+					},
+				}, nil
+			},
+		},
+	)
+
+	m := injectClientIntoManager(t, "testsvr", client)
+
+	// Manually populate tools and prompts as loadServerTools would.
+	conn := m.connectionPool.connections["testsvr"]
+	m.loadServerPrompts(ctx, "testsvr", conn)
+
+	// Also add a fake tool mapping so RemoveServer finds the server.
+	m.toolMap["testsvr__noop"] = &toolMapping{
+		serverName:   "testsvr",
+		originalName: "noop",
+	}
+	m.tools = append(m.tools, MCPTool{
+		Name:       "testsvr__noop",
+		ServerName: "testsvr",
+	})
+
+	// Verify prompts exist before removal.
+	if got := len(m.GetPrompts()); got != 1 {
+		t.Fatalf("expected 1 prompt before removal, got %d", got)
+	}
+
+	// Remove the server.
+	err := m.RemoveServer("testsvr")
+	if err != nil {
+		t.Fatalf("RemoveServer error: %v", err)
+	}
+
+	// Verify prompts are gone.
+	if got := len(m.GetPrompts()); got != 0 {
+		t.Fatalf("expected 0 prompts after removal, got %d", got)
+	}
+}
+
+func TestLoadServerPrompts_NoPromptCapability(t *testing.T) {
+	// Server without prompt capabilities — ListPrompts should fail gracefully.
+	mcpServer := server.NewMCPServer("no-prompts", "1.0.0",
+		server.WithToolCapabilities(true),
+		// No WithPromptCapabilities
+	)
+	mcpServer.AddTool(
+		mcp.NewTool("noop"),
+		func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			return mcp.NewToolResultText("ok"), nil
+		},
+	)
+
+	client, err := mcpclient.NewInProcessClient(mcpServer)
+	if err != nil {
+		t.Fatalf("NewInProcessClient: %v", err)
+	}
+	ctx := context.Background()
+	_ = client.Start(ctx)
+	initReq := mcp.InitializeRequest{}
+	initReq.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
+	initReq.Params.ClientInfo = mcp.Implementation{Name: "test", Version: "1.0"}
+	_, _ = client.Initialize(ctx, initReq)
+	t.Cleanup(func() { _ = client.Close() })
+
+	m := NewMCPToolManager()
+	conn := &MCPConnection{
+		client:     client,
+		serverName: "no-prompts",
+		isHealthy:  true,
+	}
+
+	// Should not panic or error — just silently skip.
+	m.loadServerPrompts(ctx, "no-prompts", conn)
+
+	if got := len(m.GetPrompts()); got != 0 {
+		t.Fatalf("expected 0 prompts from server without prompt capability, got %d", got)
+	}
+}
+
+func TestExtractPromptContent(t *testing.T) {
+	t.Run("TextContent", func(t *testing.T) {
+		text, parts := extractPromptContent(mcp.TextContent{Type: "text", Text: "hello world"})
+		if text != "hello world" {
+			t.Errorf("text = %q, want %q", text, "hello world")
+		}
+		if len(parts) != 0 {
+			t.Errorf("expected 0 file parts, got %d", len(parts))
+		}
+	})
+
+	t.Run("ImageContent", func(t *testing.T) {
+		// base64 of "fake image"
+		encoded := base64.StdEncoding.EncodeToString([]byte("fake image"))
+		text, parts := extractPromptContent(mcp.ImageContent{
+			Type:     "image",
+			Data:     encoded,
+			MIMEType: "image/png",
+		})
+		if text != "" {
+			t.Errorf("expected empty text, got %q", text)
+		}
+		if len(parts) != 1 {
+			t.Fatalf("expected 1 file part, got %d", len(parts))
+		}
+		if parts[0].MediaType != "image/png" {
+			t.Errorf("media type = %q, want %q", parts[0].MediaType, "image/png")
+		}
+		if parts[0].Filename != "image.png" {
+			t.Errorf("filename = %q, want %q", parts[0].Filename, "image.png")
+		}
+		if string(parts[0].Data) != "fake image" {
+			t.Errorf("data = %q, want %q", string(parts[0].Data), "fake image")
+		}
+	})
+
+	t.Run("ImageContent_DefaultMIME", func(t *testing.T) {
+		encoded := base64.StdEncoding.EncodeToString([]byte("img"))
+		_, parts := extractPromptContent(mcp.ImageContent{
+			Type: "image",
+			Data: encoded,
+			// no MIMEType → should default to image/png
+		})
+		if len(parts) != 1 {
+			t.Fatalf("expected 1 file part, got %d", len(parts))
+		}
+		if parts[0].MediaType != "image/png" {
+			t.Errorf("default MIME = %q, want %q", parts[0].MediaType, "image/png")
+		}
+	})
+
+	t.Run("AudioContent", func(t *testing.T) {
+		encoded := base64.StdEncoding.EncodeToString([]byte("fake audio"))
+		text, parts := extractPromptContent(mcp.AudioContent{
+			Type:     "audio",
+			Data:     encoded,
+			MIMEType: "audio/mp3",
+		})
+		if text != "" {
+			t.Errorf("expected empty text, got %q", text)
+		}
+		if len(parts) != 1 {
+			t.Fatalf("expected 1 file part, got %d", len(parts))
+		}
+		if parts[0].MediaType != "audio/mp3" {
+			t.Errorf("media type = %q, want %q", parts[0].MediaType, "audio/mp3")
+		}
+		if parts[0].Filename != "audio.wav" {
+			t.Errorf("filename = %q, want %q", parts[0].Filename, "audio.wav")
+		}
+	})
+
+	t.Run("EmbeddedResource_Text", func(t *testing.T) {
+		text, parts := extractPromptContent(mcp.EmbeddedResource{
+			Type: "resource",
+			Resource: mcp.TextResourceContents{
+				URI:      "file:///project/main.go",
+				MIMEType: "text/x-go",
+				Text:     "package main",
+			},
+		})
+		if text == "" {
+			t.Fatal("expected non-empty text for text resource")
+		}
+		if !strings.Contains(text, "package main") {
+			t.Errorf("text should contain resource content, got %q", text)
+		}
+		if !strings.Contains(text, "file:///project/main.go") {
+			t.Errorf("text should contain URI, got %q", text)
+		}
+		if len(parts) != 0 {
+			t.Errorf("expected 0 file parts for text resource, got %d", len(parts))
+		}
+	})
+
+	t.Run("EmbeddedResource_Blob", func(t *testing.T) {
+		blobData := []byte("binary content")
+		encoded := base64.StdEncoding.EncodeToString(blobData)
+		text, parts := extractPromptContent(mcp.EmbeddedResource{
+			Type: "resource",
+			Resource: mcp.BlobResourceContents{
+				URI:      "file:///project/data.bin",
+				MIMEType: "application/octet-stream",
+				Blob:     encoded,
+			},
+		})
+		if text != "" {
+			t.Errorf("expected empty text for blob resource, got %q", text)
+		}
+		if len(parts) != 1 {
+			t.Fatalf("expected 1 file part for blob resource, got %d", len(parts))
+		}
+		if parts[0].Filename != "data.bin" {
+			t.Errorf("filename = %q, want %q", parts[0].Filename, "data.bin")
+		}
+		if parts[0].MediaType != "application/octet-stream" {
+			t.Errorf("media type = %q, want %q", parts[0].MediaType, "application/octet-stream")
+		}
+		if string(parts[0].Data) != "binary content" {
+			t.Errorf("data = %q, want %q", string(parts[0].Data), "binary content")
+		}
+	})
+
+	t.Run("ResourceLink", func(t *testing.T) {
+		text, parts := extractPromptContent(mcp.ResourceLink{
+			Type: "resource_link",
+			URI:  "file:///docs/readme.md",
+			Name: "readme.md",
+		})
+		if text == "" {
+			t.Fatal("expected non-empty text for resource link")
+		}
+		if !strings.Contains(text, "file:///docs/readme.md") {
+			t.Errorf("text should contain URI, got %q", text)
+		}
+		if !strings.Contains(text, "readme.md") {
+			t.Errorf("text should contain name, got %q", text)
+		}
+		if len(parts) != 0 {
+			t.Errorf("expected 0 file parts for resource link, got %d", len(parts))
+		}
+	})
+
+	t.Run("InvalidBase64", func(t *testing.T) {
+		_, parts := extractPromptContent(mcp.ImageContent{
+			Type:     "image",
+			Data:     "not-valid-base64!!!",
+			MIMEType: "image/png",
+		})
+		if len(parts) != 0 {
+			t.Errorf("expected 0 file parts for invalid base64, got %d", len(parts))
+		}
+	})
+
+	t.Run("NilContent", func(t *testing.T) {
+		text, parts := extractPromptContent((*mcp.TextContent)(nil))
+		if text != "" {
+			t.Errorf("expected empty text for nil, got %q", text)
+		}
+		if len(parts) != 0 {
+			t.Errorf("expected 0 parts for nil, got %d", len(parts))
+		}
+	})
+}
+
+func TestFilenameFromURI(t *testing.T) {
+	tests := []struct {
+		uri  string
+		want string
+	}{
+		{"file:///path/to/image.png", "image.png"},
+		{"file:///single.txt", "single.txt"},
+		{"resource://server/data.json", "data.json"},
+		{"nopath", "nopath"},
+		{"", "resource"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.uri, func(t *testing.T) {
+			got := filenameFromURI(tt.uri)
+			if got != tt.want {
+				t.Errorf("filenameFromURI(%q) = %q, want %q", tt.uri, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestGetPrompt_EmbeddedResources(t *testing.T) {
+	ctx := context.Background()
+
+	imgData := base64.StdEncoding.EncodeToString([]byte("fake-png"))
+	blobData := base64.StdEncoding.EncodeToString([]byte("binary-blob"))
+
+	client := newTestPromptServer(t,
+		server.ServerPrompt{
+			Prompt: mcp.NewPrompt("review-with-files",
+				mcp.WithPromptDescription("Review with embedded resources"),
+			),
+			Handler: func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+				return &mcp.GetPromptResult{
+					Description: "Review prompt with embedded files",
+					Messages: []mcp.PromptMessage{
+						{
+							Role:    mcp.RoleUser,
+							Content: mcp.TextContent{Type: "text", Text: "Please review these files:"},
+						},
+						{
+							Role: mcp.RoleUser,
+							Content: mcp.EmbeddedResource{
+								Type: "resource",
+								Resource: mcp.TextResourceContents{
+									URI:      "file:///src/main.go",
+									MIMEType: "text/x-go",
+									Text:     "package main\n\nfunc main() {}",
+								},
+							},
+						},
+						{
+							Role: mcp.RoleUser,
+							Content: mcp.ImageContent{
+								Type:     "image",
+								Data:     imgData,
+								MIMEType: "image/png",
+							},
+						},
+						{
+							Role: mcp.RoleUser,
+							Content: mcp.EmbeddedResource{
+								Type: "resource",
+								Resource: mcp.BlobResourceContents{
+									URI:      "file:///data/model.bin",
+									MIMEType: "application/octet-stream",
+									Blob:     blobData,
+								},
+							},
+						},
+					},
+				}, nil
+			},
+		},
+	)
+
+	m := injectClientIntoManager(t, "test", client)
+
+	result, err := m.GetPrompt(ctx, "test", "review-with-files", nil)
+	if err != nil {
+		t.Fatalf("GetPrompt error: %v", err)
+	}
+	if result.Description != "Review prompt with embedded files" {
+		t.Errorf("unexpected description: %q", result.Description)
+	}
+
+	// Should have 4 messages: text, embedded text resource, image, embedded blob
+	if len(result.Messages) != 4 {
+		t.Fatalf("expected 4 messages, got %d", len(result.Messages))
+	}
+
+	// Message 0: plain text
+	msg0 := result.Messages[0]
+	if msg0.Content != "Please review these files:" {
+		t.Errorf("msg[0] content = %q", msg0.Content)
+	}
+	if len(msg0.FileParts) != 0 {
+		t.Errorf("msg[0] expected 0 file parts, got %d", len(msg0.FileParts))
+	}
+
+	// Message 1: embedded text resource → inlined as text
+	msg1 := result.Messages[1]
+	if !strings.Contains(msg1.Content, "package main") {
+		t.Errorf("msg[1] should contain resource text, got %q", msg1.Content)
+	}
+	if len(msg1.FileParts) != 0 {
+		t.Errorf("msg[1] expected 0 file parts (text resource), got %d", len(msg1.FileParts))
+	}
+
+	// Message 2: image → file part
+	msg2 := result.Messages[2]
+	if msg2.Content != "" {
+		t.Errorf("msg[2] expected empty text for image, got %q", msg2.Content)
+	}
+	if len(msg2.FileParts) != 1 {
+		t.Fatalf("msg[2] expected 1 file part, got %d", len(msg2.FileParts))
+	}
+	if msg2.FileParts[0].MediaType != "image/png" {
+		t.Errorf("msg[2] file part MIME = %q", msg2.FileParts[0].MediaType)
+	}
+	if string(msg2.FileParts[0].Data) != "fake-png" {
+		t.Errorf("msg[2] file part data = %q", string(msg2.FileParts[0].Data))
+	}
+
+	// Message 3: embedded blob resource → file part
+	msg3 := result.Messages[3]
+	if msg3.Content != "" {
+		t.Errorf("msg[3] expected empty text for blob resource, got %q", msg3.Content)
+	}
+	if len(msg3.FileParts) != 1 {
+		t.Fatalf("msg[3] expected 1 file part, got %d", len(msg3.FileParts))
+	}
+	if msg3.FileParts[0].Filename != "model.bin" {
+		t.Errorf("msg[3] filename = %q, want %q", msg3.FileParts[0].Filename, "model.bin")
+	}
+	if string(msg3.FileParts[0].Data) != "binary-blob" {
+		t.Errorf("msg[3] file part data = %q", string(msg3.FileParts[0].Data))
+	}
+}

internal/tools/mcp_test.go

@@ -103,14 +103,12 @@ func TestMCPToolManager_EmptyConfig(t *testing.T) {
 
 	// Test that we can get tool info for each tool
 	for _, tool := range tools {
-		info := tool.Info()
-
 		// Check that the tool has a valid name
-		if info.Name == "" {
+		if tool.Name == "" {
 			t.Error("Tool has empty name")
 		}
 
-		t.Logf("Tool: %s, Description: %s", info.Name, info.Description)
+		t.Logf("Tool: %s, Description: %s", tool.Name, tool.Description)
 	}
 }
 

internal/tools/oauth_flow.go

@@ -0,0 +1,116 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+
+	"github.com/mark3labs/mcp-go/client"
+	"github.com/mark3labs/mcp-go/client/transport"
+)
+
+// MCPAuthHandler is the internal interface for handling MCP OAuth flows.
+// The SDK-level kit.MCPAuthHandler is adapted to this interface in cmd/root.go
+// or pkg/kit/kit.go, keeping the tools package decoupled from the SDK.
+type MCPAuthHandler interface {
+	// RedirectURI returns the OAuth redirect URI for transport setup.
+	RedirectURI() string
+	// HandleAuth is called when a server requires OAuth authorization.
+	// It receives the server name and the authorization URL the user must visit.
+	// It returns the full callback URL (containing code and state query params)
+	// after the user completes authorization.
+	HandleAuth(ctx context.Context, serverName string, authURL string) (callbackURL string, err error)
+}
+
+// TokenStoreFactory creates a transport.TokenStore for a given MCP server URL.
+// When provided to the connection pool, it is called once per remote MCP server
+// instead of using the default file-based token store. Implementations can
+// return any transport.TokenStore — in-memory, database-backed, encrypted, etc.
+type TokenStoreFactory func(serverURL string) (transport.TokenStore, error)
+
+// OAuthFlowRunner handles the OAuth authorization flow when an MCP server
+// returns an OAuthAuthorizationRequiredError. It coordinates dynamic client
+// registration, PKCE generation, user authorization (via MCPAuthHandler),
+// and token exchange.
+type OAuthFlowRunner struct {
+	handler MCPAuthHandler
+}
+
+// NewOAuthFlowRunner creates a new OAuthFlowRunner with the given auth handler.
+func NewOAuthFlowRunner(handler MCPAuthHandler) *OAuthFlowRunner {
+	return &OAuthFlowRunner{handler: handler}
+}
+
+// RunAuthFlow executes the OAuth authorization flow for the given server.
+// It extracts the OAuthHandler from the error, performs dynamic client registration
+// if needed, generates PKCE parameters, delegates to the MCPAuthHandler for user
+// interaction, and exchanges the authorization code for a token.
+func (r *OAuthFlowRunner) RunAuthFlow(ctx context.Context, serverName string, authErr error) error {
+	// Extract the OAuthHandler from the authorization-required error.
+	oauthHandler := client.GetOAuthHandler(authErr)
+	if oauthHandler == nil {
+		return fmt.Errorf("oauth flow: failed to extract OAuth handler from error: %w", authErr)
+	}
+
+	// Perform dynamic client registration if no client ID is configured yet.
+	if oauthHandler.GetClientID() == "" {
+		if err := oauthHandler.RegisterClient(ctx, "kit"); err != nil {
+			return fmt.Errorf("oauth flow: dynamic client registration failed: %w", err)
+		}
+	}
+
+	// Generate PKCE code verifier and challenge.
+	codeVerifier, err := client.GenerateCodeVerifier()
+	if err != nil {
+		return fmt.Errorf("oauth flow: failed to generate code verifier: %w", err)
+	}
+	codeChallenge := client.GenerateCodeChallenge(codeVerifier)
+
+	// Generate a random state parameter for CSRF protection.
+	state, err := client.GenerateState()
+	if err != nil {
+		return fmt.Errorf("oauth flow: failed to generate state: %w", err)
+	}
+
+	// Build the authorization URL the user needs to visit.
+	authURL, err := oauthHandler.GetAuthorizationURL(ctx, state, codeChallenge)
+	if err != nil {
+		return fmt.Errorf("oauth flow: failed to get authorization URL: %w", err)
+	}
+
+	// Delegate to the MCPAuthHandler for user-facing authorization (e.g. open
+	// browser, wait for redirect). It returns the full callback URL containing
+	// the authorization code and state.
+	callbackURL, err := r.handler.HandleAuth(ctx, serverName, authURL)
+	if err != nil {
+		return fmt.Errorf("oauth flow: user authorization failed: %w", err)
+	}
+
+	// Parse the callback URL to extract the authorization code and state.
+	parsed, err := url.Parse(callbackURL)
+	if err != nil {
+		return fmt.Errorf("oauth flow: failed to parse callback URL: %w", err)
+	}
+
+	code := parsed.Query().Get("code")
+	returnedState := parsed.Query().Get("state")
+
+	if code == "" {
+		return fmt.Errorf("oauth flow: callback URL missing 'code' parameter")
+	}
+	if returnedState == "" {
+		return fmt.Errorf("oauth flow: callback URL missing 'state' parameter")
+	}
+
+	// Exchange the authorization code for an access token.
+	if err := oauthHandler.ProcessAuthorizationResponse(ctx, code, returnedState, codeVerifier); err != nil {
+		return fmt.Errorf("oauth flow: token exchange failed: %w", err)
+	}
+
+	return nil
+}
+
+// IsOAuthError returns true if the error is an OAuthAuthorizationRequiredError.
+func IsOAuthError(err error) bool {
+	return client.IsOAuthAuthorizationRequiredError(err)
+}

internal/tools/testdata/echo_server.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Minimal MCP server over stdio for testing. Exposes one tool: echo."""
+import json
+import sys
+
+
+def read_message():
+    """Read a JSON-RPC message from stdin."""
+    line = sys.stdin.readline()
+    if not line:
+        return None
+    return json.loads(line.strip())
+
+
+def write_message(msg):
+    """Write a JSON-RPC message to stdout."""
+    sys.stdout.write(json.dumps(msg) + "\n")
+    sys.stdout.flush()
+
+
+def handle(msg):
+    method = msg.get("method", "")
+    mid = msg.get("id")
+
+    if method == "initialize":
+        write_message({
+            "jsonrpc": "2.0",
+            "id": mid,
+            "result": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "test-echo", "version": "1.0.0"},
+            },
+        })
+    elif method == "notifications/initialized":
+        pass  # no response needed
+    elif method == "tools/list":
+        write_message({
+            "jsonrpc": "2.0",
+            "id": mid,
+            "result": {
+                "tools": [
+                    {
+                        "name": "echo",
+                        "description": "Echoes the input text back.",
+                        "inputSchema": {
+                            "type": "object",
+                            "properties": {
+                                "text": {"type": "string", "description": "Text to echo"}
+                            },
+                            "required": ["text"],
+                        },
+                    },
+                    {
+                        "name": "greet",
+                        "description": "Returns a greeting.",
+                        "inputSchema": {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string", "description": "Name to greet"}
+                            },
+                            "required": ["name"],
+                        },
+                    },
+                ]
+            },
+        })
+    elif method == "tools/call":
+        tool_name = msg["params"]["name"]
+        args = msg["params"].get("arguments", {})
+        if tool_name == "echo":
+            text = args.get("text", "")
+            write_message({
+                "jsonrpc": "2.0",
+                "id": mid,
+                "result": {
+                    "content": [{"type": "text", "text": text}]
+                },
+            })
+        elif tool_name == "greet":
+            name = args.get("name", "World")
+            write_message({
+                "jsonrpc": "2.0",
+                "id": mid,
+                "result": {
+                    "content": [{"type": "text", "text": f"Hello, {name}!"}]
+                },
+            })
+        else:
+            write_message({
+                "jsonrpc": "2.0",
+                "id": mid,
+                "error": {"code": -32601, "message": f"Unknown tool: {tool_name}"},
+            })
+    elif method == "ping":
+        write_message({"jsonrpc": "2.0", "id": mid, "result": {}})
+    else:
+        if mid is not None:
+            write_message({
+                "jsonrpc": "2.0",
+                "id": mid,
+                "error": {"code": -32601, "message": f"Unknown method: {method}"},
+            })
+
+
+if __name__ == "__main__":
+    while True:
+        msg = read_message()
+        if msg is None:
+            break
+        handle(msg)

internal/tools/token_store.go

@@ -0,0 +1,155 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/mark3labs/mcp-go/client/transport"
+)
+
+// Compile-time check that FileTokenStore implements transport.TokenStore.
+var _ transport.TokenStore = (*FileTokenStore)(nil)
+
+// FileTokenStore is a file-backed implementation of transport.TokenStore that
+// persists OAuth tokens as JSON on disk. Tokens are stored in a shared JSON file
+// keyed by server URL, allowing multiple MCP servers to maintain independent tokens.
+//
+// The token file is located at $XDG_CONFIG_HOME/.kit/mcp_tokens.json, falling back
+// to ~/.config/.kit/mcp_tokens.json when XDG_CONFIG_HOME is not set.
+//
+// FileTokenStore is safe for concurrent use.
+type FileTokenStore struct {
+	serverKey string
+	filePath  string
+	mu        sync.RWMutex
+}
+
+// NewFileTokenStore creates a new FileTokenStore for the given server URL.
+// The serverKey is used as the map key in the shared token file, and should
+// typically be the MCP server's base URL.
+//
+// Returns an error if the token file path cannot be resolved.
+func NewFileTokenStore(serverKey string) (*FileTokenStore, error) {
+	filePath, err := resolveTokenFilePath()
+	if err != nil {
+		return nil, fmt.Errorf("resolving token file path: %w", err)
+	}
+
+	return &FileTokenStore{
+		serverKey: serverKey,
+		filePath:  filePath,
+	}, nil
+}
+
+// GetToken returns the stored token for this store's server key.
+// Returns transport.ErrNoToken if no token exists for the server key or if
+// the token file does not yet exist.
+// Returns context.Canceled or context.DeadlineExceeded if the context is done.
+func (s *FileTokenStore) GetToken(ctx context.Context) (*transport.Token, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	tokens, err := readTokenFile(s.filePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, transport.ErrNoToken
+		}
+		return nil, fmt.Errorf("reading token file: %w", err)
+	}
+
+	token, ok := tokens[s.serverKey]
+	if !ok {
+		return nil, transport.ErrNoToken
+	}
+
+	return token, nil
+}
+
+// SaveToken persists the given token for this store's server key.
+// If the token file or its parent directories do not exist, they are created.
+// Existing tokens for other server keys are preserved.
+// Returns context.Canceled or context.DeadlineExceeded if the context is done.
+func (s *FileTokenStore) SaveToken(ctx context.Context, token *transport.Token) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	tokens, err := readTokenFile(s.filePath)
+	if err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("reading token file: %w", err)
+	}
+	if tokens == nil {
+		tokens = make(map[string]*transport.Token)
+	}
+
+	tokens[s.serverKey] = token
+
+	if err := writeTokenFile(s.filePath, tokens); err != nil {
+		return fmt.Errorf("writing token file: %w", err)
+	}
+
+	return nil
+}
+
+// resolveTokenFilePath determines the path to the token file using
+// XDG_CONFIG_HOME if set, otherwise falling back to ~/.config/.kit/.
+func resolveTokenFilePath() (string, error) {
+	configDir := os.Getenv("XDG_CONFIG_HOME")
+	if configDir == "" {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("determining user home directory: %w", err)
+		}
+		configDir = filepath.Join(home, ".config")
+	}
+
+	return filepath.Join(configDir, ".kit", "mcp_tokens.json"), nil
+}
+
+// readTokenFile reads and unmarshals the token file into a server-keyed map.
+// Returns os.ErrNotExist (via os.IsNotExist) if the file does not exist.
+func readTokenFile(path string) (map[string]*transport.Token, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+
+	var tokens map[string]*transport.Token
+	if err := json.Unmarshal(data, &tokens); err != nil {
+		return nil, fmt.Errorf("unmarshaling token file: %w", err)
+	}
+
+	return tokens, nil
+}
+
+// writeTokenFile marshals the token map and writes it to disk, creating
+// parent directories as needed. The file is written with 0600 permissions
+// to protect sensitive token data.
+func writeTokenFile(path string, tokens map[string]*transport.Token) error {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return fmt.Errorf("creating token directory %s: %w", dir, err)
+	}
+
+	data, err := json.MarshalIndent(tokens, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshaling tokens: %w", err)
+	}
+
+	if err := os.WriteFile(path, data, 0600); err != nil {
+		return fmt.Errorf("writing token file %s: %w", path, err)
+	}
+
+	return nil
+}

internal/ui/block_renderer.go

@@ -4,6 +4,8 @@ import (
 	"image/color"
 
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // blockRenderer handles rendering of content blocks with configurable options
@@ -175,7 +177,7 @@ func renderContentBlock(content string, containerWidth int, options ...rendering
 		borderChars = 1
 	}
 
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	// Resolve foreground color: caller override or theme default.
 	fgColor := theme.Text

internal/ui/children_test.go

@@ -6,6 +6,7 @@ import (
 
 	tea "charm.land/bubbletea/v2"
 	"github.com/mark3labs/kit/internal/app"
+	"github.com/mark3labs/kit/internal/ui/core"
 )
 
 // ==========================================================================
@@ -59,7 +60,7 @@ func TestInputComponent_SubmitEmitsSubmitMsg(t *testing.T) {
 		t.Fatal("expected a cmd from pressing enter on non-empty input")
 	}
 
-	sm, ok := msg.(submitMsg)
+	sm, ok := msg.(core.SubmitMsg)
 	if !ok {
 		t.Fatalf("expected submitMsg, got %T", msg)
 	}
@@ -83,7 +84,7 @@ func TestInputComponent_CtrlD_SubmitEmitsSubmitMsg(t *testing.T) {
 	if msg == nil {
 		t.Fatal("expected a cmd from ctrl+d on non-empty input")
 	}
-	sm, ok := msg.(submitMsg)
+	sm, ok := msg.(core.SubmitMsg)
 	if !ok {
 		t.Fatalf("expected submitMsg from ctrl+d, got %T", msg)
 	}
@@ -175,7 +176,7 @@ func TestInputComponent_ClearForwardsAsSubmitMsg(t *testing.T) {
 				t.Fatalf("%s: expected submitMsg cmd, got nil", alias)
 			}
 			msg := runCmd(cmd)
-			sm, ok := msg.(submitMsg)
+			sm, ok := msg.(core.SubmitMsg)
 			if !ok {
 				t.Fatalf("%s: expected submitMsg, got %T", alias, msg)
 			}
@@ -230,7 +231,7 @@ func TestInputComponent_ClearQueue_ForwardsAsSubmitMsg(t *testing.T) {
 				t.Fatalf("%s: expected submitMsg cmd, got nil", alias)
 			}
 			msg := runCmd(cmd)
-			sm, ok := msg.(submitMsg)
+			sm, ok := msg.(core.SubmitMsg)
 			if !ok {
 				t.Fatalf("%s: expected submitMsg, got %T", alias, msg)
 			}
@@ -258,7 +259,7 @@ func TestInputComponent_UnknownSlashCommand_ForwardsAsSubmit(t *testing.T) {
 	if msg == nil {
 		t.Fatal("expected submitMsg for unknown slash command")
 	}
-	sm, ok := msg.(submitMsg)
+	sm, ok := msg.(core.SubmitMsg)
 	if !ok {
 		t.Fatalf("expected submitMsg for unknown slash command, got %T", msg)
 	}
@@ -701,167 +702,35 @@ func TestStreamComponent_StaleFlushTick_Discarded(t *testing.T) {
 
 // TestStreamComponent_ConsumeOverflow_NoHeight verifies that when height is
 // unconstrained (0), ConsumeOverflow always returns "".
-func TestStreamComponent_ConsumeOverflow_NoHeight(t *testing.T) {
+func TestStreamComponent_ConsumeOverflow_NoOp(t *testing.T) {
 	c := newTestStream()
 	// Commit some content directly.
 	c.streamContent.WriteString("line1\nline2\nline3")
 	c.phase = streamPhaseActive
-	c.renderDirty = true
 
+	// ConsumeOverflow is a no-op in alt screen mode — always returns "".
 	if got := c.ConsumeOverflow(); got != "" {
-		t.Fatalf("expected empty with height=0, got %q", got)
+		t.Fatalf("expected empty from no-op ConsumeOverflow, got %q", got)
 	}
-}
-
-// TestStreamComponent_ConsumeOverflow_NoOverflow verifies that when content fits
-// within the allocated height, ConsumeOverflow returns "".
-func TestStreamComponent_ConsumeOverflow_NoOverflow(t *testing.T) {
-	c := newTestStream()
-	c.streamContent.WriteString("line1\nline2")
-	c.phase = streamPhaseActive
-	c.renderDirty = true
-	c.height = 20 // plenty of room
 
+	// Also returns "" with a height set.
+	c.height = 2
 	if got := c.ConsumeOverflow(); got != "" {
-		t.Fatalf("expected empty when content fits, got %q", got)
+		t.Fatalf("expected empty from no-op ConsumeOverflow with height, got %q", got)
 	}
 }
 
-// TestStreamComponent_ConsumeOverflow_EmitsTopLines verifies that when the
-// rendered content has more lines than the allocated height, ConsumeOverflow
-// returns the top overflow lines and advances the internal pointer.
-func TestStreamComponent_ConsumeOverflow_EmitsTopLines(t *testing.T) {
+// TestStreamComponent_GetRenderedContent_ReturnsAll verifies that
+// GetRenderedContent returns all accumulated content.
+func TestStreamComponent_GetRenderedContent_ReturnsAll(t *testing.T) {
 	c := newTestStream()
-	c.height = 2
-
-	// Build raw content that when "rendered" (plain text for this test)
-	// is 5 lines — we bypass the markdown renderer by writing directly to
-	// streamContent and using a nil renderer.
 	c.renderer = nil
+	c.phase = streamPhaseActive
+
 	c.streamContent.WriteString("a\nb\nc\nd\ne")
-	c.phase = streamPhaseActive
-	c.renderDirty = true
-
-	// First call: should return lines a, b, c (5 lines - 2 visible = 3 overflow).
-	overflow1 := c.ConsumeOverflow()
-	if overflow1 == "" {
-		t.Fatal("expected overflow, got empty")
-	}
-	overflowLines := strings.Split(overflow1, "\n")
-	if len(overflowLines) != 3 {
-		t.Fatalf("expected 3 overflow lines, got %d: %q", len(overflowLines), overflow1)
-	}
-	if overflowLines[0] != "a" || overflowLines[1] != "b" || overflowLines[2] != "c" {
-		t.Fatalf("unexpected overflow lines: %v", overflowLines)
-	}
-
-	// Second call without new content should return "" (pointer already advanced).
-	overflow2 := c.ConsumeOverflow()
-	if overflow2 != "" {
-		t.Fatalf("expected empty on second call, got %q", overflow2)
-	}
-}
-
-// TestStreamComponent_ConsumeOverflow_IncrementalFlush verifies that as new
-// content arrives, ConsumeOverflow incrementally returns only newly overflowed
-// lines on each call.
-func TestStreamComponent_ConsumeOverflow_IncrementalFlush(t *testing.T) {
-	c := newTestStream()
-	c.height = 2
-	c.renderer = nil
-	c.phase = streamPhaseActive
-
-	// Start with 3 lines — 1 overflows.
-	c.streamContent.WriteString("a\nb\nc")
-	c.renderDirty = true
-
-	overflow1 := c.ConsumeOverflow()
-	if overflow1 != "a" {
-		t.Fatalf("expected 'a', got %q", overflow1)
-	}
-
-	// Add 2 more lines — 2 additional overflows.
-	c.streamContent.WriteString("\nd\ne")
-	c.renderDirty = true
-
-	overflow2 := c.ConsumeOverflow()
-	want := "b\nc"
-	if overflow2 != want {
-		t.Fatalf("expected %q, got %q", want, overflow2)
-	}
-}
-
-// TestStreamComponent_ConsumeOverflow_ResetClearsPointer verifies that Reset()
-// resets the scrollback pointer so the next response starts fresh.
-func TestStreamComponent_ConsumeOverflow_ResetClearsPointer(t *testing.T) {
-	c := newTestStream()
-	c.height = 1
-	c.renderer = nil
-	c.phase = streamPhaseActive
-
-	c.streamContent.WriteString("a\nb")
-	c.renderDirty = true
-	overflow := c.ConsumeOverflow()
-	if overflow != "a" {
-		t.Fatalf("expected 'a', got %q", overflow)
-	}
-
-	c.Reset()
-	if c.scrollbackFlushedLines != 0 {
-		t.Fatalf("expected scrollbackFlushedLines=0 after Reset, got %d", c.scrollbackFlushedLines)
-	}
-}
-
-// TestStreamComponent_GetRenderedContent_SkipsFlushedLines verifies that
-// GetRenderedContent skips lines already emitted via ConsumeOverflow so the
-// caller doesn't re-print content already in the terminal scrollback.
-func TestStreamComponent_GetRenderedContent_SkipsFlushedLines(t *testing.T) {
-	c := newTestStream()
-	c.height = 2
-	c.renderer = nil
-	c.phase = streamPhaseActive
-
-	// 5 lines → 3 overflow, 2 visible.
-	c.streamContent.WriteString("a\nb\nc\nd\ne")
-	c.renderDirty = true
-
-	// Consume the overflow: lines a, b, c.
-	overflow := c.ConsumeOverflow()
-	if overflow != "a\nb\nc" {
-		t.Fatalf("expected 'a\\nb\\nc', got %q", overflow)
-	}
-	if c.scrollbackFlushedLines != 3 {
-		t.Fatalf("expected flushedLines=3, got %d", c.scrollbackFlushedLines)
-	}
-
-	// GetRenderedContent should only return the non-flushed portion: d, e.
-	got := c.GetRenderedContent()
-	if got != "d\ne" {
-		t.Fatalf("expected 'd\\ne', got %q", got)
-	}
-}
-
-// TestStreamComponent_GetRenderedContent_AllFlushed verifies that when all
-// lines have been pushed via ConsumeOverflow, GetRenderedContent returns "".
-func TestStreamComponent_GetRenderedContent_AllFlushed(t *testing.T) {
-	c := newTestStream()
-	c.height = 1
-	c.renderer = nil
-	c.phase = streamPhaseActive
-
-	// 2 lines → height=1, so 1 overflow.
-	c.streamContent.WriteString("a\nb")
-	c.renderDirty = true
-
-	// Consume overflow (line a), leaving 1 visible line (b).
-	_ = c.ConsumeOverflow()
-
-	// Now bump height so everything overflows — simulate a resize that made
-	// the viewable area 0, forcing all content to be "flushed".
-	c.scrollbackFlushedLines = 2 // pretend both lines were flushed
 
 	got := c.GetRenderedContent()
-	if got != "" {
-		t.Fatalf("expected empty when all lines flushed, got %q", got)
+	if got != "a\nb\nc\nd\ne" {
+		t.Fatalf("expected full content, got %q", got)
 	}
 }

internal/ui/cli.go

@@ -5,9 +5,10 @@ import (
 	"os"
 	"time"
 
-	"charm.land/fantasy"
 	"charm.land/lipgloss/v2"
 	"golang.org/x/term"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // CLI manages the command-line interface for KIT, providing message rendering,
@@ -125,7 +126,7 @@ func (c *CLI) DisplayInfo(message string) {
 // DisplayExtensionBlock renders a custom styled block with the given border
 // color and optional subtitle. Used by extensions via ctx.PrintBlock.
 func (c *CLI) DisplayExtensionBlock(text, borderColor, subtitle string) {
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	borderClr := theme.Info
 	if borderColor != "" {
@@ -171,33 +172,6 @@ func (c *CLI) DisplayDebugConfig(config map[string]any) {
 	fmt.Println(c.renderer.RenderDebugConfigMessage(config, time.Now()).Content)
 }
 
-// UpdateUsageFromResponse records token usage using metadata from the fantasy
-// response. Only actual API-reported tokens are used for cost tracking.
-// If the provider doesn't report token counts, no usage is recorded.
-func (c *CLI) UpdateUsageFromResponse(response *fantasy.Response, inputText string) {
-	if c.usageTracker == nil {
-		return
-	}
-
-	usage := response.Usage
-	inputTokens := int(usage.InputTokens)
-	outputTokens := int(usage.OutputTokens)
-
-	// Only use actual API-reported tokens for cost tracking.
-	// We intentionally do NOT estimate tokens - estimation is inaccurate
-	// and should never be used for cost calculations.
-	if inputTokens > 0 {
-		cacheReadTokens := int(usage.CacheReadTokens)
-		cacheWriteTokens := int(usage.CacheCreationTokens)
-		c.usageTracker.UpdateUsage(inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens)
-		// Per-response usage is a single API call, so it represents the
-		// actual context window fill level.
-		c.usageTracker.SetContextTokens(inputTokens + outputTokens)
-	}
-	// If inputTokens is 0, the provider didn't report usage - we skip recording
-	// rather than estimating, to ensure cost accuracy.
-}
-
 // DisplayUsageAfterResponse renders and displays token usage information immediately
 // following an AI response. This provides real-time feedback about the cost and
 // token consumption of each interaction.

internal/ui/clipboard.go

@@ -1,96 +0,0 @@
-package ui
-
-import (
-	"fmt"
-	"runtime"
-
-	tea "charm.land/bubbletea/v2"
-	"github.com/atotto/clipboard"
-)
-
-// CopyToClipboard writes text to both the system clipboard and via OSC 52.
-// Returns a tea.Cmd that can be used in Bubble Tea's Update flow.
-func CopyToClipboard(text string) tea.Cmd {
-	if text == "" {
-		return nil
-	}
-
-	return tea.Sequence(
-		// Method 1: OSC 52 escape sequence (works in modern terminals)
-		tea.SetClipboard(text),
-
-		// Method 2: Native system clipboard (atotto/clipboard)
-		func() tea.Msg {
-			// Best effort - ignore errors
-			_ = clipboard.WriteAll(text)
-			return nil
-		},
-	)
-}
-
-// CopyToClipboardWithMessage writes text to clipboard and returns a toast notification.
-func CopyToClipboardWithMessage(text string, message string) tea.Cmd {
-	if text == "" {
-		return nil
-	}
-
-	return tea.Sequence(
-		CopyToClipboard(text),
-		func() tea.Msg {
-			return ToastMsg{Message: message, Type: ToastInfo}
-		},
-	)
-}
-
-// ToastType represents the type of toast notification.
-type ToastType int
-
-const (
-	ToastInfo ToastType = iota
-	ToastSuccess
-	ToastWarning
-	ToastError
-)
-
-// ToastMsg is a message to display a toast notification.
-type ToastMsg struct {
-	Message string
-	Type    ToastType
-}
-
-// IsClipboardSupported returns true if the clipboard is supported on this platform.
-func IsClipboardSupported() bool {
-	// atotto/clipboard supports Linux (with xclip or xsel), macOS, Windows
-	switch runtime.GOOS {
-	case "darwin", "windows":
-		return true
-	case "linux":
-		// Check if xclip or xsel is available
-		// This is a best-effort check
-		return true
-	default:
-		return false
-	}
-}
-
-// CopySelection represents a text selection with start/end positions.
-type CopySelection struct {
-	StartItemIdx int  // Index of item where selection starts
-	StartLine    int  // Line within item where selection starts
-	StartCol     int  // Column where selection starts
-	EndItemIdx   int  // Index of item where selection ends
-	EndLine      int  // Line within item where selection ends
-	EndCol       int  // Column where selection ends
-	Active       bool // Whether selection is currently active
-}
-
-// IsEmpty returns true if the selection has no content.
-func (s CopySelection) IsEmpty() bool {
-	return !s.Active || (s.StartItemIdx == s.EndItemIdx && s.StartLine == s.EndLine && s.StartCol == s.EndCol)
-}
-
-// String returns a string representation for debugging.
-func (s CopySelection) String() string {
-	return fmt.Sprintf("Selection{item:%d-%d, line:%d-%d, col:%d-%d, active:%v}",
-		s.StartItemIdx, s.EndItemIdx, s.StartLine, s.EndLine, s.StartCol, s.EndCol, s.Active)
-}

internal/ui/clipboard/clipboard.go

@@ -0,0 +1,26 @@
+package clipboard
+
+import (
+	tea "charm.land/bubbletea/v2"
+	"github.com/atotto/clipboard"
+)
+
+// CopyToClipboard writes text to both the system clipboard and via OSC 52.
+// Returns a tea.Cmd that can be used in Bubble Tea's Update flow.
+func CopyToClipboard(text string) tea.Cmd {
+	if text == "" {
+		return nil
+	}
+
+	return tea.Sequence(
+		// Method 1: OSC 52 escape sequence (works in modern terminals)
+		tea.SetClipboard(text),
+
+		// Method 2: Native system clipboard (atotto/clipboard)
+		func() tea.Msg {
+			// Best effort - ignore errors
+			_ = clipboard.WriteAll(text)
+			return nil
+		},
+	)
+}

internal/ui/commands/commands.go

@@ -1,4 +1,4 @@
-package ui
+package commands
 
 import (
 	"slices"
@@ -7,6 +7,10 @@ import (
 	"github.com/mark3labs/kit/internal/models"
 )
 
+// ListThemesFunc is set by the ui package to provide theme name completion.
+// This breaks the circular dependency between commands and ui packages.
+var ListThemesFunc func() []string
+
 // SlashCommand represents a user-invokable slash command with its metadata.
 // Commands can have multiple aliases and are organized by category for better
 // discoverability and help display.
@@ -16,6 +20,7 @@ type SlashCommand struct {
 	Aliases     []string
 	Category    string                       // e.g., "Navigation", "System", "Info"
 	Complete    func(prefix string) []string // optional argument tab-completion
+	HasArgs     bool                         // true when the command expects arguments (e.g. prompt templates with placeholders)
 }
 
 // SlashCommands provides the global registry of all available slash commands
@@ -99,7 +104,10 @@ var SlashCommands = []SlashCommand{
 		Description: "Switch color theme (e.g. /theme catppuccin)",
 		Category:    "System",
 		Complete: func(prefix string) []string {
-			names := ListThemes()
+			if ListThemesFunc == nil {
+				return nil
+			}
+			names := ListThemesFunc()
 			if prefix == "" {
 				return names
 			}
@@ -112,6 +120,12 @@ var SlashCommands = []SlashCommand{
 			return matches
 		},
 	},
+	{
+		Name:        "/reload-ext",
+		Description: "Hot-reload all extensions from disk",
+		Category:    "System",
+		Aliases:     []string{"/re"},
+	},
 	{
 		Name:        "/quit",
 		Description: "Exit the application",
@@ -127,7 +141,7 @@ var SlashCommands = []SlashCommand{
 	},
 	{
 		Name:        "/fork",
-		Description: "Branch from an earlier message",
+		Description: "Fork to new session from an earlier message",
 		Category:    "Navigation",
 	},
 	{

internal/ui/core/events.go

@@ -1,4 +1,4 @@
-package ui
+package core
 
 // 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
@@ -10,9 +10,9 @@ type ImageAttachment struct {
 	MediaType string
 }
 
-// submitMsg is sent by the InputComponent when the user submits a text prompt.
+// 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 {
+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.
@@ -20,10 +20,10 @@ type submitMsg struct {
 	Images []ImageAttachment
 }
 
-// cancelTimerExpiredMsg is sent by the tea.Tick command that starts when the user
+// CancelTimerExpiredMsg is sent by the tea.Tick command that starts when the user
 // presses ESC once during stateWorking. If this message arrives before the user
 // presses ESC a second time, the canceling state is reset to false.
-type cancelTimerExpiredMsg struct{}
+type CancelTimerExpiredMsg struct{}
 
 // --- Tree session events ---
 
@@ -42,14 +42,14 @@ 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
+// 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 {
+type ShellCommandMsg struct {
 	// Command is the shell command to execute (prefix stripped).
 	Command string
 	// ExcludeFromContext is true for !! (output excluded from LLM context),
@@ -57,9 +57,9 @@ type shellCommandMsg struct {
 	ExcludeFromContext bool
 }
 
-// shellCommandResultMsg carries the result of a shell command execution
+// ShellCommandResultMsg carries the result of a shell command execution
 // back to the parent model for display.
-type shellCommandResultMsg struct {
+type ShellCommandResultMsg struct {
 	// Command is the original shell command that was executed.
 	Command string
 	// Output is the combined stdout/stderr output.
@@ -68,6 +68,6 @@ type shellCommandResultMsg struct {
 	ExitCode int
 	// Err is non-nil if the command failed to start or timed out.
 	Err error
-	// ExcludeFromContext mirrors the flag from shellCommandMsg.
+	// ExcludeFromContext mirrors the flag from ShellCommandMsg.
 	ExcludeFromContext bool
 }

internal/ui/event_handler.go

@@ -139,7 +139,9 @@ func (h *CLIEventHandler) Handle(msg tea.Msg) {
 		case "block":
 			h.cli.DisplayExtensionBlock(e.Text, e.BorderColor, e.Subtitle)
 		default:
-			fmt.Println(e.Text)
+			// Route unstyled extension prints through the system message
+			// renderer so they get consistent formatting and timestamps.
+			h.cli.DisplayInfo(e.Text)
 		}
 
 	case app.StepCompleteEvent:

internal/ui/exports.go

@@ -0,0 +1,69 @@
+package ui
+
+// This file re-exports types from subpackages for backward compatibility.
+// External importers can continue using ui.XXX without needing to import
+// from subpackages directly.
+
+import (
+	"github.com/mark3labs/kit/internal/ui/commands"
+	"github.com/mark3labs/kit/internal/ui/core"
+	"github.com/mark3labs/kit/internal/ui/fileutil"
+	"github.com/mark3labs/kit/internal/ui/prefs"
+	"github.com/mark3labs/kit/internal/ui/style"
+)
+
+// Re-export from core package
+type (
+	ImageAttachment       = core.ImageAttachment
+	SubmitMsg             = core.SubmitMsg
+	CancelTimerExpiredMsg = core.CancelTimerExpiredMsg
+	TreeNodeSelectedMsg   = core.TreeNodeSelectedMsg
+	TreeCancelledMsg      = core.TreeCancelledMsg
+	ShellCommandMsg       = core.ShellCommandMsg
+	ShellCommandResultMsg = core.ShellCommandResultMsg
+)
+
+// Re-export from commands package
+type (
+	SlashCommand     = commands.SlashCommand
+	ExtensionCommand = commands.ExtensionCommand
+)
+
+// Re-export functions and types from fileutil package
+var ProcessFileAttachments = fileutil.ProcessFileAttachments
+
+// Re-export types from fileutil
+type (
+	FileAttachmentResult = fileutil.FileAttachmentResult
+	FilePart             = fileutil.FilePart
+	MCPResourceReader    = fileutil.MCPResourceReader
+)
+
+// Re-export from prefs package
+var (
+	LoadThemePreference         = prefs.LoadThemePreference
+	SaveThemePreference         = prefs.SaveThemePreference
+	LoadModelPreference         = prefs.LoadModelPreference
+	SaveModelPreference         = prefs.SaveModelPreference
+	LoadThinkingLevelPreference = prefs.LoadThinkingLevelPreference
+	SaveThinkingLevelPreference = prefs.SaveThinkingLevelPreference
+)
+
+// Re-export from style package
+type (
+	Theme               = style.Theme
+	MarkdownThemeColors = style.MarkdownThemeColors
+)
+
+var (
+	GetTheme                = style.GetTheme
+	SetTheme                = style.SetTheme
+	DefaultTheme            = style.DefaultTheme
+	ApplyTheme              = style.ApplyTheme
+	ApplyThemeWithoutSave   = style.ApplyThemeWithoutSave
+	ListThemes              = style.ListThemes
+	RegisterThemeFromConfig = style.RegisterThemeFromConfig
+	KitBanner               = style.KitBanner
+	AdaptiveColor           = style.AdaptiveColor
+	IsDarkBackground        = style.IsDarkBackground
+)

internal/ui/factory.go

@@ -109,9 +109,7 @@ func SetupCLI(opts *CLISetupOptions) (*CLI, error) {
 		}
 	}
 
-	fmt.Println("")
-
-	// Display model info
+	// Display model info (the system message block provides its own spacing).
 	if provider != "unknown" && model != "unknown" {
 		cli.DisplayInfo(fmt.Sprintf("Model loaded: %s (%s)", provider, model))
 	}

internal/ui/file_processor.go

@@ -1,129 +0,0 @@
-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

@@ -8,15 +8,24 @@ import (
 	"strings"
 )
 
-// FileSuggestion represents a single file or directory suggestion for the @
-// autocomplete popup.
+// FileSuggestion represents a single file, directory, or MCP resource
+// suggestion for the @ autocomplete popup.
 type FileSuggestion struct {
-	// RelPath is the path relative to the search base (e.g. "cmd/kit/main.go").
+	// RelPath is the path relative to the search base (e.g. "cmd/kit/main.go")
+	// or a display name for MCP resources (e.g. "mcp:server/resource-name").
 	RelPath string
 	// IsDir is true when the entry is a directory.
 	IsDir bool
 	// Score is the fuzzy match score (higher is better).
 	Score int
+	// IsMCPResource is true for MCP resource entries.
+	IsMCPResource bool
+	// MCPServerName is the MCP server name (set when IsMCPResource is true).
+	MCPServerName string
+	// MCPResourceURI is the MCP resource URI (set when IsMCPResource is true).
+	MCPResourceURI string
+	// MCPMIMEType is the MIME type hint from the MCP server.
+	MCPMIMEType string
 }
 
 // maxFileSuggestions is the maximum number of file suggestions returned.

internal/ui/fileutil/processor.go

@@ -0,0 +1,321 @@
+package fileutil
+
+import (
+	"fmt"
+	"mime"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/mark3labs/kit/internal/fences"
+)
+
+// FilePart represents a binary file attachment (image, audio, etc.) extracted
+// from an @file reference. Callers convert this to kit.LLMFilePart before
+// sending to the LLM. Defined here to avoid a circular dependency on pkg/kit.
+type FilePart struct {
+	// Filename is the basename of the file (e.g. "photo.png").
+	Filename string
+	// Data is the raw file bytes.
+	Data []byte
+	// MediaType is the MIME type (e.g. "image/png", "audio/wav").
+	MediaType string
+}
+
+// MCPResourceReader is a callback function that reads an MCP resource by
+// server name and URI. Returns text content, binary data, MIME type, and error.
+// Used by ProcessFileAttachments to resolve @mcp:server:uri tokens.
+type MCPResourceReader func(serverName, uri string) (text string, blobData []byte, mimeType string, isBlob bool, err error)
+
+// FileAttachmentResult is the result of processing @file references in user
+// input. Text files are inlined as XML in ProcessedText; binary files (images,
+// audio, video, PDFs) are returned as FileParts for multimodal submission.
+type FileAttachmentResult struct {
+	// ProcessedText is the user's text with @file tokens replaced:
+	// text files become XML-wrapped content, binary file tokens are removed.
+	ProcessedText string
+	// FileParts contains binary file attachments extracted from @file
+	// references. Empty when all referenced files are text.
+	FileParts []FilePart
+}
+
+// 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 a result containing the processed
+// text and any binary file attachments. Text files are XML-wrapped inline;
+// binary files (images, audio, etc.) are extracted as FileParts for multimodal
+// submission. Non-file @ tokens (like email addresses) are left unchanged.
+//
+// MCP resources are supported via @mcp:server:uri tokens. The optional
+// mcpReader callback is used to resolve them; pass nil to skip MCP resources.
+func ProcessFileAttachments(text string, cwd string, mcpReader ...MCPResourceReader) FileAttachmentResult {
+	var reader MCPResourceReader
+	if len(mcpReader) > 0 {
+		reader = mcpReader[0]
+	}
+	var allParts []FilePart
+	processed := fences.ReplaceOutside(text, func(segment string) string {
+		result, parts := processFileTokens(segment, cwd, reader)
+		allParts = append(allParts, parts...)
+		return result
+	})
+	return FileAttachmentResult{
+		ProcessedText: processed,
+		FileParts:     allParts,
+	}
+}
+
+// processFileTokens handles @file replacement in a single text segment
+// that is known to be outside fenced code blocks. Returns the processed
+// text and any binary file parts extracted.
+func processFileTokens(text string, cwd string, mcpReader MCPResourceReader) (string, []FilePart) {
+	tokens := fileTokenPattern.FindAllString(text, -1)
+	if len(tokens) == 0 {
+		return text, nil
+	}
+
+	var parts []FilePart
+	result := text
+	for _, token := range tokens {
+		path := tokenToPath(token)
+		if path == "" {
+			continue
+		}
+
+		// Check for MCP resource reference: @mcp:server:uri
+		if strings.HasPrefix(path, "mcp:") {
+			if mcpReader == nil {
+				continue
+			}
+			mcpRef := path[4:] // strip "mcp:"
+			// Split into server:uri (first colon separates server from URI)
+			serverName, uri, ok := strings.Cut(mcpRef, ":")
+			if !ok || serverName == "" || uri == "" {
+				continue // invalid format
+			}
+
+			textContent, blobData, mimeType, isBlob, err := mcpReader(serverName, uri)
+			if err != nil {
+				continue // skip on error, leave token as-is
+			}
+
+			if isBlob {
+				// Binary MCP resource → extract as FilePart.
+				filename := filepath.Base(uri)
+				if filename == "." || filename == "/" {
+					filename = serverName + "_resource"
+				}
+				parts = append(parts, FilePart{
+					Filename:  filename,
+					Data:      blobData,
+					MediaType: mimeType,
+				})
+				result = strings.Replace(result, token, "", 1)
+			} else {
+				// Text MCP resource → inline as XML.
+				wrapped := fmt.Sprintf("<resource uri=\"%s\" server=\"%s\">\n%s\n</resource>", uri, serverName, textContent)
+				result = strings.Replace(result, token, wrapped, 1)
+			}
+			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
+		}
+
+		mediaType := detectMediaType(absPath, content)
+
+		if isBinaryMediaType(mediaType) {
+			// Binary file → extract as a FilePart for multimodal submission.
+			// Remove the @token from the text.
+			parts = append(parts, FilePart{
+				Filename:  filepath.Base(absPath),
+				Data:      content,
+				MediaType: mediaType,
+			})
+			result = strings.Replace(result, token, "", 1)
+		} else {
+			// Text file → inline as XML-wrapped content.
+			wrapped := wrapFileContent(absPath, content)
+			result = strings.Replace(result, token, wrapped, 1)
+		}
+	}
+
+	// Clean up any extra whitespace left by removed binary tokens.
+	result = strings.TrimSpace(result)
+
+	return result, parts
+}
+
+// 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))
+}
+
+// detectMediaType determines the MIME type of a file using extension-based
+// lookup first (more reliable for known types), then falls back to content
+// sniffing via net/http.DetectContentType.
+func detectMediaType(path string, content []byte) string {
+	// Extension-based detection is more reliable for well-known types.
+	ext := strings.ToLower(filepath.Ext(path))
+	if mt := mime.TypeByExtension(ext); mt != "" {
+		// mime.TypeByExtension returns types like "image/png; charset=utf-8"
+		// — strip parameters.
+		if base, _, ok := strings.Cut(mt, ";"); ok {
+			return strings.TrimSpace(base)
+		}
+		return mt
+	}
+
+	// Known extensions that mime package may miss.
+	switch ext {
+	case ".webp":
+		return "image/webp"
+	case ".avif":
+		return "image/avif"
+	case ".heic", ".heif":
+		return "image/heif"
+	case ".opus":
+		return "audio/opus"
+	case ".flac":
+		return "audio/flac"
+	case ".m4a":
+		return "audio/mp4"
+	case ".wasm":
+		return "application/wasm"
+	}
+
+	// Content sniffing fallback.
+	if len(content) > 0 {
+		detected := http.DetectContentType(content)
+		if detected != "" && detected != "application/octet-stream" {
+			if base, _, ok := strings.Cut(detected, ";"); ok {
+				return strings.TrimSpace(base)
+			}
+			return detected
+		}
+	}
+
+	// Default: treat as plain text so it gets XML-wrapped.
+	return "text/plain"
+}
+
+// isBinaryMediaType returns true if the MIME type represents a binary file
+// that should be sent as a multimodal FilePart rather than XML-wrapped text.
+func isBinaryMediaType(mediaType string) bool {
+	// Image types — always binary.
+	if strings.HasPrefix(mediaType, "image/") {
+		return true
+	}
+	// Audio types — always binary.
+	if strings.HasPrefix(mediaType, "audio/") {
+		return true
+	}
+	// Video types — always binary.
+	if strings.HasPrefix(mediaType, "video/") {
+		return true
+	}
+	// Specific application types that are binary.
+	switch mediaType {
+	case "application/pdf",
+		"application/zip",
+		"application/gzip",
+		"application/x-tar",
+		"application/octet-stream",
+		"application/wasm",
+		"application/x-executable",
+		"application/vnd.ms-excel",
+		"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		"application/vnd.ms-powerpoint",
+		"application/vnd.openxmlformats-officedocument.presentationml.presentation",
+		"application/msword",
+		"application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+		return true
+	}
+	return false
+}

internal/ui/fileutil/processor_test.go

@@ -0,0 +1,203 @@
+package fileutil
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestProcessFileAttachments_TextFile(t *testing.T) {
+	// Create a temp text file
+	dir := t.TempDir()
+	textFile := filepath.Join(dir, "hello.txt")
+	if err := os.WriteFile(textFile, []byte("hello world"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	text := "@" + textFile + " check this out"
+	result := ProcessFileAttachments(text, dir)
+
+	if len(result.FileParts) != 0 {
+		t.Errorf("expected 0 FileParts for text file, got %d", len(result.FileParts))
+	}
+	if result.ProcessedText == text {
+		t.Error("expected text file to be XML-wrapped, but got original text unchanged")
+	}
+	// Should contain XML wrapping
+	if !contains(result.ProcessedText, "<file path=") {
+		t.Error("expected XML <file> wrapping in processed text")
+	}
+	if !contains(result.ProcessedText, "hello world") {
+		t.Error("expected file content in processed text")
+	}
+}
+
+func TestProcessFileAttachments_BinaryFile(t *testing.T) {
+	// Create a minimal PNG file (binary)
+	dir := t.TempDir()
+	pngFile := filepath.Join(dir, "image.png")
+	// Minimal valid PNG header
+	pngData := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, // PNG signature
+		0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52, // IHDR chunk
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, // 1x1
+		0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xDE, // 8bit RGB
+		0x00, 0x00, 0x00, 0x0C, 0x49, 0x44, 0x41, 0x54, // IDAT chunk
+		0x08, 0xD7, 0x63, 0xF8, 0xCF, 0xC0, 0x00, 0x00,
+		0x00, 0x02, 0x00, 0x01, 0xE2, 0x21, 0xBC, 0x33,
+		0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, // IEND chunk
+		0xAE, 0x42, 0x60, 0x82,
+	}
+	if err := os.WriteFile(pngFile, pngData, 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	text := "@" + pngFile + " what is this image?"
+	result := ProcessFileAttachments(text, dir)
+
+	if len(result.FileParts) != 1 {
+		t.Fatalf("expected 1 FilePart for binary file, got %d", len(result.FileParts))
+	}
+	if result.FileParts[0].MediaType != "image/png" {
+		t.Errorf("expected media type image/png, got %s", result.FileParts[0].MediaType)
+	}
+	if result.FileParts[0].Filename != "image.png" {
+		t.Errorf("expected filename image.png, got %s", result.FileParts[0].Filename)
+	}
+	// The @token should be removed from the text
+	if contains(result.ProcessedText, "@") && contains(result.ProcessedText, pngFile) {
+		t.Error("expected @token to be removed from processed text for binary file")
+	}
+	if contains(result.ProcessedText, "what is this image?") {
+		// Good, the prompt text should remain
+	} else {
+		t.Error("expected prompt text to remain in processed text")
+	}
+}
+
+func TestProcessFileAttachments_MCPResource(t *testing.T) {
+	// Test @mcp:server:uri token processing with a mock reader
+	text := "@mcp:test-server:docs://readme tell me about this"
+	reader := func(serverName, uri string) (string, []byte, string, bool, error) {
+		if serverName != "test-server" || uri != "docs://readme" {
+			t.Errorf("unexpected server/uri: %s/%s", serverName, uri)
+		}
+		return "Hello from MCP resource", nil, "text/plain", false, nil
+	}
+
+	result := ProcessFileAttachments(text, "/tmp", reader)
+
+	if len(result.FileParts) != 0 {
+		t.Errorf("expected 0 FileParts for text MCP resource, got %d", len(result.FileParts))
+	}
+	if !contains(result.ProcessedText, "<resource uri=\"docs://readme\" server=\"test-server\">") {
+		t.Error("expected <resource> XML wrapping in processed text")
+	}
+	if !contains(result.ProcessedText, "Hello from MCP resource") {
+		t.Error("expected MCP resource content in processed text")
+	}
+}
+
+func TestProcessFileAttachments_MCPResource_Binary(t *testing.T) {
+	// Test @mcp:server:uri token processing for a binary resource
+	text := "@mcp:test-server:images://logo describe this"
+	reader := func(serverName, uri string) (string, []byte, string, bool, error) {
+		if serverName != "test-server" || uri != "images://logo" {
+			t.Errorf("unexpected server/uri: %s/%s", serverName, uri)
+		}
+		return "", []byte{0x89, 0x50, 0x4E, 0x47}, "image/png", true, nil
+	}
+
+	result := ProcessFileAttachments(text, "/tmp", reader)
+
+	if len(result.FileParts) != 1 {
+		t.Fatalf("expected 1 FilePart for binary MCP resource, got %d", len(result.FileParts))
+	}
+	if result.FileParts[0].MediaType != "image/png" {
+		t.Errorf("expected media type image/png, got %s", result.FileParts[0].MediaType)
+	}
+	if result.FileParts[0].Filename != "logo" {
+		t.Errorf("expected filename 'logo', got %s", result.FileParts[0].Filename)
+	}
+	// The @token should be removed from the text
+	if contains(result.ProcessedText, "@mcp:") {
+		t.Error("expected @mcp: token to be removed from processed text for binary resource")
+	}
+}
+
+func TestProcessFileAttachments_NoReader(t *testing.T) {
+	// Without an MCP reader, @mcp: tokens should be left as-is
+	text := "@mcp:server:resource this is a test"
+	result := ProcessFileAttachments(text, "/tmp")
+
+	if len(result.FileParts) != 0 {
+		t.Errorf("expected 0 FileParts, got %d", len(result.FileParts))
+	}
+	// The @mcp: token should remain unchanged since no reader was provided
+	if result.ProcessedText != text {
+		t.Errorf("expected text unchanged without reader, got: %s", result.ProcessedText)
+	}
+}
+
+func TestDetectMediaType(t *testing.T) {
+	tests := []struct {
+		ext      string
+		content  []byte
+		expected string
+	}{
+		{".go", nil, "text/plain"}, // .go falls back to content sniffing → text/plain
+		{".png", []byte{0x89, 0x50, 0x4E, 0x47}, "image/png"},
+		{".jpg", []byte{0xFF, 0xD8, 0xFF}, "image/jpeg"},
+		{".pdf", []byte{0x25, 0x50, 0x44, 0x46}, "application/pdf"},
+		{".txt", []byte("hello"), "text/plain"},
+		{".wav", nil, "audio/wav"},
+		{".webp", nil, "image/webp"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.ext, func(t *testing.T) {
+			got := detectMediaType("test"+tt.ext, tt.content)
+			if got != tt.expected {
+				t.Errorf("detectMediaType(%q) = %q, want %q", tt.ext, got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestIsBinaryMediaType(t *testing.T) {
+	tests := []struct {
+		mimeType string
+		expected bool
+	}{
+		{"image/png", true},
+		{"image/jpeg", true},
+		{"audio/wav", true},
+		{"video/mp4", true},
+		{"application/pdf", true},
+		{"text/plain", false},
+		{"text/go", false},
+		{"application/json", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.mimeType, func(t *testing.T) {
+			got := isBinaryMediaType(tt.mimeType)
+			if got != tt.expected {
+				t.Errorf("isBinaryMediaType(%q) = %v, want %v", tt.mimeType, got, tt.expected)
+			}
+		})
+	}
+}
+
+func contains(s, substr string) bool {
+	return len(s) >= len(substr) && (s == substr || len(s) > 0 && containsStr(s, substr))
+}
+
+func containsStr(s, substr string) bool {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return true
+		}
+	}
+	return false
+}

internal/ui/format.go

@@ -5,6 +5,8 @@ import (
 	"time"
 
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // Renderer is the interface satisfied by MessageRenderer. It allows model.go
@@ -30,7 +32,7 @@ var _ Renderer = (*MessageRenderer)(nil)
 // combined, styled output string with tags stripped.
 //
 // Shared by MessageRenderer.
-func parseBashOutput(result string, theme Theme) string {
+func parseBashOutput(result string, theme style.Theme) string {
 	var formattedResult strings.Builder
 	remaining := result
 

internal/ui/fuzzy.go

@@ -2,20 +2,22 @@ package ui
 
 import (
 	"strings"
+
+	"github.com/mark3labs/kit/internal/ui/commands"
 )
 
 // FuzzyMatch represents the result of a fuzzy string matching operation,
 // containing the matched command and its relevance score. Higher scores
 // indicate better matches.
 type FuzzyMatch struct {
-	Command *SlashCommand
+	Command *commands.SlashCommand
 	Score   int
 }
 
 // FuzzyMatchCommands performs fuzzy string matching on the provided slash commands
 // based on the query string. Returns a slice of matches sorted by relevance score
 // in descending order. An empty query returns all commands with zero scores.
-func FuzzyMatchCommands(query string, commands []SlashCommand) []FuzzyMatch {
+func FuzzyMatchCommands(query string, commands []commands.SlashCommand) []FuzzyMatch {
 	if query == "" || query == "/" {
 		// Return all commands when query is empty or just "/"
 		matches := make([]FuzzyMatch, len(commands))
@@ -57,7 +59,7 @@ func FuzzyMatchCommands(query string, commands []SlashCommand) []FuzzyMatch {
 }
 
 // fuzzyScore calculates the fuzzy match score for a command
-func fuzzyScore(query string, cmd *SlashCommand) int {
+func fuzzyScore(query string, cmd *commands.SlashCommand) int {
 	// Check exact match first
 	cmdName := strings.ToLower(strings.TrimPrefix(cmd.Name, "/"))
 	if cmdName == query {

internal/ui/input.go

@@ -2,6 +2,7 @@ package ui
 
 import (
 	"fmt"
+	"sort"
 	"strings"
 
 	"charm.land/bubbles/v2/key"
@@ -10,6 +11,9 @@ import (
 	"charm.land/lipgloss/v2"
 
 	"github.com/mark3labs/kit/internal/clipboard"
+	"github.com/mark3labs/kit/internal/ui/commands"
+	"github.com/mark3labs/kit/internal/ui/core"
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // InputComponent is the interactive text input field for the parent AppModel.
@@ -29,7 +33,7 @@ import (
 // app.Run().
 type InputComponent struct {
 	textarea    textarea.Model
-	commands    []SlashCommand
+	commands    []commands.SlashCommand
 	showPopup   bool
 	filtered    []FuzzyMatch
 	selected    int
@@ -42,22 +46,26 @@ type InputComponent struct {
 	// Argument completion state. When the user types "/cmd " followed by
 	// a partial argument and the command has a Complete function, the popup
 	// switches to argument-completion mode showing suggestions from Complete.
-	argMode      bool           // true when showing arg completions
-	argCommand   string         // command prefix for arg mode (e.g. "/bookmark")
-	argSynthCmds []SlashCommand // backing storage for synthetic arg entries
+	argMode      bool                    // true when showing arg completions
+	argCommand   string                  // command prefix for arg mode (e.g. "/bookmark")
+	argSynthCmds []commands.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
+	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   []commands.SlashCommand // synthetic commands.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
 
+	// mcpResources is a callback that returns available MCP resources for
+	// the @ autocomplete popup. Set by the parent via SetMCPResourceProvider.
+	mcpResources func() []FileSuggestion
+
 	// appCtrl is used for slash commands that mutate app state.
 	// May be nil in tests; nil-safe.
 	appCtrl AppController
@@ -66,12 +74,12 @@ type InputComponent struct {
 	hideHint bool
 
 	// agentBusy indicates the agent is currently working. When true, the
-	// hint text shows steering shortcut (Ctrl+S) instead of submit.
+	// hint text shows steering shortcut (Ctrl+X s) instead of submit.
 	agentBusy 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
+	pendingImages []core.ImageAttachment
 
 	// history stores previously submitted prompts (most recent last).
 	// Limited to maxHistory entries; duplicates of the previous entry are
@@ -94,7 +102,7 @@ const maxHistory = 100
 
 // clipboardImageMsg is the result of an async clipboard image read.
 type clipboardImageMsg struct {
-	image *ImageAttachment
+	image *core.ImageAttachment
 	err   error
 }
 
@@ -106,7 +114,7 @@ func NewInputComponent(width int, title string, appCtrl AppController) *InputCom
 	ta.Placeholder = "Type your message..."
 	ta.ShowLineNumbers = false
 	ta.Prompt = ""
-	ta.CharLimit = 5000
+	ta.CharLimit = 0
 	ta.SetWidth(width - 8) // Account for container padding, border and internal padding
 	ta.SetHeight(3)        // Default to 3 lines like huh
 	ta.Focus()
@@ -119,7 +127,7 @@ func NewInputComponent(width int, title string, appCtrl AppController) *InputCom
 	)
 
 	// Style the textarea using theme colors.
-	theme := GetTheme()
+	theme := style.GetTheme()
 	styles := ta.Styles()
 	styles.Focused.Base = lipgloss.NewStyle()
 	styles.Focused.Placeholder = lipgloss.NewStyle().Foreground(theme.VeryMuted)
@@ -130,7 +138,7 @@ func NewInputComponent(width int, title string, appCtrl AppController) *InputCom
 
 	return &InputComponent{
 		textarea:    ta,
-		commands:    SlashCommands,
+		commands:    commands.SlashCommands,
 		width:       width,
 		popupHeight: 7,
 		title:       title,
@@ -144,6 +152,12 @@ func (s *InputComponent) SetCwd(cwd string) {
 	s.cwd = cwd
 }
 
+// SetMCPResourceProvider sets a callback that returns MCP resource suggestions
+// for the @ autocomplete popup. Called by the parent after construction.
+func (s *InputComponent) SetMCPResourceProvider(fn func() []FileSuggestion) {
+	s.mcpResources = fn
+}
+
 // Init implements tea.Model. Starts the cursor blink animation.
 func (s *InputComponent) Init() tea.Cmd {
 	return textarea.Blink
@@ -282,16 +296,25 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 						s.textarea.CursorEnd()
 						return s, nil
 					}
+					selectedCmd := s.filtered[s.selected].Command
 					// Populate textarea with selected item and submit on next tick.
 					if s.argMode {
-						s.textarea.SetValue(s.argCommand + " " + s.filtered[s.selected].Command.Name)
+						s.textarea.SetValue(s.argCommand + " " + selectedCmd.Name)
 					} else {
-						s.textarea.SetValue(s.filtered[s.selected].Command.Name)
+						s.textarea.SetValue(selectedCmd.Name)
 					}
 					s.textarea.CursorEnd()
 					s.showPopup = false
 					s.selected = 0
-					s.submitNext = true
+					// If the selected command expects arguments, populate
+					// the input with the command + trailing space so the
+					// user can type args, instead of auto-submitting.
+					if !s.argMode && selectedCmd.HasArgs {
+						s.textarea.SetValue(selectedCmd.Name + " ")
+						s.textarea.CursorEnd()
+					} else {
+						s.submitNext = true
+					}
 					return s, nil
 				}
 				return s, nil
@@ -320,24 +343,63 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 			// 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 hasAt, prefix, atIdx := ExtractAtPrefix(line, cursorCol); hasAt {
+				var suggestions []FileSuggestion
+
+				// Local file suggestions (only if cwd is set).
+				if s.cwd != "" {
+					suggestions = GetFileSuggestions(prefix, s.cwd)
+				}
+
+				// MCP resource suggestions — merge with file suggestions.
+				if s.mcpResources != nil {
+					mcpSuggestions := s.mcpResources()
+					if prefix != "" {
+						// Fuzzy-filter MCP resources against the typed prefix.
+						queryLower := strings.ToLower(prefix)
+						var filtered []FileSuggestion
+						for _, r := range mcpSuggestions {
+							score := scoreFilePath(queryLower, r.RelPath)
+							if score <= 0 {
+								// Also try matching against the resource name without prefix.
+								score = scoreFilePath(queryLower, r.MCPServerName+"/"+r.RelPath)
+							}
+							if score > 0 {
+								r.Score = score
+								filtered = append(filtered, r)
+							}
+						}
+						mcpSuggestions = filtered
+					}
+					suggestions = append(suggestions, mcpSuggestions...)
+				}
+
 				if len(suggestions) > 0 {
+					// Sort by score descending, cap at maxFileSuggestions.
+					sort.Slice(suggestions, func(i, j int) bool {
+						return suggestions[i].Score > suggestions[j].Score
+					})
+					if len(suggestions) > maxFileSuggestions {
+						suggestions = suggestions[:maxFileSuggestions]
+					}
+
 					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.fileSynthCmds = make([]commands.SlashCommand, len(suggestions))
 					s.filtered = make([]FuzzyMatch, len(suggestions))
 					for i, fs := range suggestions {
 						name := fs.RelPath
 						desc := ""
 						if fs.IsDir {
 							desc = "directory"
+						} else if fs.IsMCPResource {
+							desc = "mcp:" + fs.MCPServerName
 						}
-						s.fileSynthCmds[i] = SlashCommand{Name: name, Description: desc}
+						s.fileSynthCmds[i] = commands.SlashCommand{Name: name, Description: desc}
 						s.filtered[i] = FuzzyMatch{Command: &s.fileSynthCmds[i], Score: fs.Score}
 					}
 					s.selected = 0
@@ -396,14 +458,14 @@ func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 		cmd := strings.TrimSpace(trimmed[2:])
 		if cmd != "" {
 			return func() tea.Msg {
-				return shellCommandMsg{Command: cmd, ExcludeFromContext: true}
+				return core.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}
+				return core.ShellCommandMsg{Command: cmd, ExcludeFromContext: false}
 			}
 		}
 	}
@@ -411,9 +473,9 @@ func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 	// Resolve via canonical command lookup so aliases are handled uniformly.
 	// Only /quit is handled locally — all other slash commands (including
 	// /clear and /clear-queue) are forwarded to the parent model via
-	// submitMsg so the parent can update its own state (scrollback, queue
+	// submitMsg so the parent can update its own state (ScrollList, queue
 	// counts, etc.) in one place.
-	if sc := GetCommandByName(trimmed); sc != nil {
+	if sc := commands.GetCommandByName(trimmed); sc != nil {
 		switch sc.Name {
 		case "/quit":
 			return tea.Quit
@@ -426,7 +488,7 @@ func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 	images := s.pendingImages
 	s.pendingImages = nil
 	return func() tea.Msg {
-		return submitMsg{Text: trimmed, Images: images}
+		return core.SubmitMsg{Text: trimmed, Images: images}
 	}
 }
 
@@ -463,7 +525,7 @@ func (s *InputComponent) resetHistoryBrowsing() {
 func (s *InputComponent) View() tea.View {
 	containerStyle := lipgloss.NewStyle()
 
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	// PaddingLeft(3) aligns with message content: border(1) + paddingLeft(2).
 	titleStyle := lipgloss.NewStyle().
@@ -511,19 +573,21 @@ func (s *InputComponent) View() tea.View {
 		availableHintWidth := s.width - 3
 		if s.agentBusy {
 			// When the agent is working, show steering shortcut.
-			if availableHintWidth >= 55 {
-				hint = "enter queue • ctrl+s steer • esc esc cancel"
-			} else if availableHintWidth >= 35 {
-				hint = "↵ queue • ^S steer • esc×2 cancel"
+			if availableHintWidth >= 60 {
+				hint = "enter queue • ctrl+x s steer • esc esc cancel"
+			} else if availableHintWidth >= 40 {
+				hint = "↵ queue • ^X s steer • esc×2 cancel"
 			} else {
-				hint = "^S steer"
+				hint = "^X s steer"
 			}
+		} else if availableHintWidth >= 80 {
+			hint = "enter submit • ctrl+j / shift+enter new line • ctrl+x e editor • ctrl+v paste image"
 		} else if availableHintWidth >= 67 {
-			hint = "enter submit • ctrl+j / shift+enter new line • ctrl+v paste image"
+			hint = "enter submit • ctrl+j new line • ctrl+x e editor • ctrl+v image"
 		} else if availableHintWidth >= 40 {
-			hint = "↵ submit • ctrl+j newline • ctrl+v image"
+			hint = "↵ submit • ctrl+j newline • ^X e editor"
 		} else if availableHintWidth >= 20 {
-			hint = "↵ submit • ctrl+j"
+			hint = "↵ submit • ^X e editor"
 		} else {
 			hint = "↵ submit"
 		}
@@ -531,14 +595,7 @@ func (s *InputComponent) View() tea.View {
 		view.WriteString(helpStyle.Render(hint))
 	}
 
-	v := tea.NewView(containerStyle.Render(view.String()))
-	v.AltScreen = true
-	v.MouseMode = tea.MouseModeCellMotion
-	v.ReportFocus = true
-	v.KeyboardEnhancements = tea.KeyboardEnhancements{
-		ReportEventTypes: true,
-	}
-	return v
+	return tea.NewView(containerStyle.Render(view.String()))
 }
 
 // renderPopup renders the autocomplete popup for slash command suggestions.
@@ -565,18 +622,39 @@ func (s *InputComponent) RenderPopupCentered(termWidth, termHeight int) string {
 
 // renderPopupWithOptions renders the popup content with optional center styling.
 func (s *InputComponent) renderPopupWithOptions(centered bool) string {
-	theme := GetTheme()
+	theme := style.GetTheme()
 	popupWidth := max(s.width-4, 20)
+
+	// Use the theme background for the popup - the full-width item backgrounds
+	// and primary-colored selection will provide sufficient contrast
+	popupBg := theme.Background
+
 	popupStyle := lipgloss.NewStyle().
 		Border(lipgloss.RoundedBorder()).
-		BorderForeground(theme.MutedBorder).
+		BorderForeground(theme.Primary).
+		Background(popupBg).
 		Padding(1, 2).
 		Width(popupWidth).
-		MarginLeft(0)
+		MarginLeft(0).
+		MarginBottom(1) // Visual depth/shadow effect
 
 	// Inner content width: popup minus border (2) and horizontal padding (4).
 	innerWidth := max(popupWidth-6, 10)
 
+	// Item background styles for high contrast
+	normalItemBg := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.Text).
+		Width(innerWidth).
+		Padding(0, 1)
+
+	selectedItemBg := lipgloss.NewStyle().
+		Background(theme.Primary).
+		Foreground(theme.Background).
+		Width(innerWidth).
+		Padding(0, 1).
+		Bold(true)
+
 	var items []string
 
 	visibleItems := min(len(s.filtered), s.popupHeight)
@@ -590,44 +668,45 @@ func (s *InputComponent) renderPopupWithOptions(centered bool) string {
 		match := s.filtered[i]
 		sc := match.Command
 
+		// Choose the appropriate background style
+		itemStyle := normalItemBg
+		if i == s.selected {
+			itemStyle = selectedItemBg
+		}
+
+		// Build indicator with proper coloring
 		var indicator string
 		if i == s.selected {
-			indicator = lipgloss.NewStyle().Foreground(theme.Primary).Render("> ")
+			indicator = "> "
 		} else {
 			indicator = "  "
 		}
 
-		nameStyle := lipgloss.NewStyle().Foreground(theme.Secondary).Bold(true)
-		descStyle := lipgloss.NewStyle().Foreground(theme.Muted)
-		if i == s.selected {
-			nameStyle = nameStyle.Foreground(theme.Primary)
-			descStyle = descStyle.Foreground(theme.Text)
-		}
-
+		// Build content with name and description
+		var content string
 		if s.fileMode {
-			// File mode: use full width for the path, show description
-			// (e.g. "directory") inline after a gap.
+			// File mode: use full width for the path, show description inline
 			maxNameLen := max(innerWidth-16, 8)
 			displayName := sc.Name
 			if len(displayName) > maxNameLen && maxNameLen > 3 {
 				displayName = displayName[:maxNameLen-3] + "..."
 			}
-			name := nameStyle.Render(displayName)
+
 			if sc.Description != "" && innerWidth > 30 {
-				items = append(items, indicator+name+"  "+descStyle.Render(sc.Description))
+				content = indicator + displayName + "  " + sc.Description
 			} else {
-				items = append(items, indicator+name)
+				content = indicator + displayName
 			}
 		} else {
-			// Line layout: indicator(2) + name(nameWidth-2 visual) + desc.
+			// Line layout: indicator(2) + name(nameWidth-2 visual) + desc
 			if innerWidth < 20 {
-				// Very narrow: show truncated name only, no fixed column.
+				// Very narrow: show truncated name only
 				displayName := sc.Name
 				maxName := max(innerWidth-2, 3)
 				if len(displayName) > maxName {
 					displayName = displayName[:maxName-1] + "…"
 				}
-				items = append(items, indicator+nameStyle.Render(displayName))
+				content = indicator + displayName
 			} else {
 				nameWidth := 15
 				if innerWidth < 25 {
@@ -638,33 +717,41 @@ func (s *InputComponent) renderPopupWithOptions(centered bool) string {
 				if len(displayName) > maxNameChars {
 					displayName = displayName[:maxNameChars-1] + "…"
 				}
-				name := nameStyle.Width(maxNameChars).Render(displayName)
 
-				// Description gets remaining space.
+				// Description gets remaining space
 				maxDescLen := max(innerWidth-nameWidth, 0)
 				desc := sc.Description
-				if maxDescLen < 4 {
-					items = append(items, indicator+name)
-				} else {
+				if maxDescLen >= 4 && desc != "" {
 					if len(desc) > maxDescLen {
 						desc = desc[:maxDescLen-3] + "..."
 					}
-					items = append(items, indicator+name+descStyle.Render(desc))
+					content = indicator + lipgloss.NewStyle().Width(maxNameChars).Render(displayName) + desc
+				} else {
+					content = indicator + displayName
 				}
 			}
 		}
+
+		items = append(items, itemStyle.Render(content))
 	}
 
+	// Add scroll indicators with background
+	scrollStyle := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.VeryMuted).
+		Width(innerWidth).
+		Padding(0, 1)
+
 	if startIdx > 0 {
-		items = append([]string{lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("  ↑ more above")}, items...)
+		items = append([]string{scrollStyle.Render("  ↑ more above")}, items...)
 	}
 	if endIdx < len(s.filtered) {
-		items = append(items, lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("  ↓ more below"))
+		items = append(items, scrollStyle.Render("  ↓ more below"))
 	}
 
 	content := strings.Join(items, "\n")
 
-	// Adapt footer text to available width.
+	// Adapt footer text to available width with background
 	var footerText string
 	if innerWidth >= 50 {
 		footerText = "↑↓ navigate • tab complete • ↵ select • esc dismiss"
@@ -673,7 +760,10 @@ func (s *InputComponent) renderPopupWithOptions(centered bool) string {
 	} else {
 		footerText = "↑↓ tab ↵ esc"
 	}
-	footer := lipgloss.NewStyle().Foreground(theme.VeryMuted).Italic(true).
+	footer := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.VeryMuted).
+		Italic(true).
 		Render(footerText)
 
 	return popupStyle.Render(content + "\n\n" + footer)
@@ -703,10 +793,10 @@ func (s *InputComponent) completeArgs(line string) []FuzzyMatch {
 
 	s.argMode = true
 	s.argCommand = cmdName
-	s.argSynthCmds = make([]SlashCommand, len(suggestions))
+	s.argSynthCmds = make([]commands.SlashCommand, len(suggestions))
 	s.filtered = make([]FuzzyMatch, len(suggestions))
 	for i, sug := range suggestions {
-		s.argSynthCmds[i] = SlashCommand{Name: sug}
+		s.argSynthCmds[i] = commands.SlashCommand{Name: sug}
 		s.filtered[i] = FuzzyMatch{Command: &s.argSynthCmds[i]}
 	}
 	return s.filtered
@@ -714,7 +804,7 @@ func (s *InputComponent) completeArgs(line string) []FuzzyMatch {
 
 // findCommandWithComplete looks up a command by name that has a non-nil
 // Complete function.
-func (s *InputComponent) findCommandWithComplete(name string) *SlashCommand {
+func (s *InputComponent) findCommandWithComplete(name string) *commands.SlashCommand {
 	for i := range s.commands {
 		if s.commands[i].Name == name && s.commands[i].Complete != nil {
 			return &s.commands[i]
@@ -732,7 +822,7 @@ func readClipboardImageCmd() tea.Cmd {
 			return clipboardImageMsg{err: err}
 		}
 		return clipboardImageMsg{
-			image: &ImageAttachment{
+			image: &core.ImageAttachment{
 				Data:      img.Data,
 				MediaType: img.MediaType,
 			},
@@ -742,7 +832,7 @@ func readClipboardImageCmd() tea.Cmd {
 
 // ClearPendingImages removes all pending image attachments and returns them.
 // Used by the parent model when consuming images for submission.
-func (s *InputComponent) ClearPendingImages() []ImageAttachment {
+func (s *InputComponent) ClearPendingImages() []core.ImageAttachment {
 	images := s.pendingImages
 	s.pendingImages = nil
 	return images
@@ -754,8 +844,9 @@ func (s *InputComponent) PendingImageCount() int {
 }
 
 // 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.
+// file or MCP resource suggestion. For directories, it keeps the popup open
+// for further drilling. For files and resources, it closes the popup and adds
+// a trailing space.
 func (s *InputComponent) applyFileCompletion(idx int) {
 	if idx >= len(s.fileSuggestions) {
 		return
@@ -772,19 +863,30 @@ func (s *InputComponent) applyFileCompletion(idx int) {
 
 	// 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 {
+	if suggestion.IsMCPResource {
+		// MCP resources use @mcp:server:uri format.
+		// Quote if the URI contains spaces.
+		ref := "mcp:" + suggestion.MCPServerName + ":" + suggestion.MCPResourceURI
+		if strings.Contains(ref, " ") {
+			replacement = `@"` + ref + `"`
+		} else {
+			replacement = "@" + ref
+		}
 		replacement += " "
+	} else {
+		needsQuote := strings.Contains(suggestion.RelPath, " ")
+		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
@@ -796,7 +898,7 @@ func (s *InputComponent) applyFileCompletion(idx int) {
 	s.textarea.SetValue(newValue)
 	s.textarea.CursorEnd()
 
-	if suggestion.IsDir {
+	if suggestion.IsDir && !suggestion.IsMCPResource {
 		// Keep popup open — trigger a refresh for the new directory.
 		s.lastValue = "" // force re-evaluation on next update tick
 	} else {

internal/ui/message_items.go

@@ -6,6 +6,9 @@ import (
 	"time"
 
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/render"
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // --------------------------------------------------------------------------
@@ -143,47 +146,20 @@ func (s *StreamingMessageItem) Render(width int) string {
 		return s.cachedRender
 	}
 
-	// Get renderer from context
-	renderer := newMessageRenderer(width, false)
-
 	var rendered string
 	if s.role == "reasoning" {
-		// Render as reasoning/thinking block with live duration counter
-		theme := GetTheme()
-		mutedStyle := lipgloss.NewStyle().Foreground(theme.Muted)
-		ty := createTypography(theme)
-		content := strings.TrimLeft(s.content, " \t\n")
-
-		var parts []string
-		parts = append(parts, mutedStyle.Render(ty.Italic(content)))
-
-		// Add live duration counter (updates on each render)
-		var duration time.Duration
+		// Calculate duration in milliseconds for render.ReasoningBlock
+		var durationMs int64
 		if s.finalDuration > 0 {
-			// Streaming complete, show frozen duration
-			duration = s.finalDuration
+			durationMs = s.finalDuration.Milliseconds()
 		} else if !s.startTime.IsZero() {
-			// Still streaming, show live duration
-			duration = time.Since(s.startTime)
+			durationMs = time.Since(s.startTime).Milliseconds()
 		}
-
-		if duration > 0 {
-			var durationStr string
-			if duration < time.Second {
-				durationStr = fmt.Sprintf("%dms", duration.Milliseconds())
-			} else {
-				durationStr = fmt.Sprintf("%.1fs", duration.Seconds())
-			}
-			label := lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("Thought for ")
-			durationStyled := lipgloss.NewStyle().Foreground(theme.Accent).Render(durationStr)
-			parts = append(parts, label+durationStyled)
-		}
-
-		rendered = styleMarginBottom1.Render(strings.Join(parts, "\n"))
+		ty := createTypography(style.GetTheme())
+		rendered = render.ReasoningBlock(s.content, durationMs, ty, style.GetTheme())
 	} else {
 		// Render as assistant message
-		msg := renderer.RenderAssistantMessage(s.content, s.timestamp, s.modelName)
-		rendered = msg.Content
+		rendered = render.AssistantBlock(s.content, width, style.GetTheme())
 	}
 
 	// Cache and return (but reasoning is never cached due to live duration)
@@ -196,10 +172,17 @@ func (s *StreamingMessageItem) Render(width int) string {
 
 // Height returns the number of lines.
 func (s *StreamingMessageItem) Height() int {
-	if s.cachedRender == "" {
+	// For reasoning blocks, cachedRender is never populated (rendering is
+	// width-independent and includes a live timer). Fall back to Render(0)
+	// so callers always get the correct height.
+	rendered := s.cachedRender
+	if rendered == "" {
+		rendered = s.Render(0)
+	}
+	if rendered == "" {
 		return 0
 	}
-	return strings.Count(s.cachedRender, "\n") + 1
+	return strings.Count(rendered, "\n") + 1
 }
 
 // AppendChunk adds a content chunk and invalidates the render cache.
@@ -255,7 +238,7 @@ func (m *StreamingBashOutputItem) Render(width int) string {
 		return m.cachedRender
 	}
 
-	theme := GetTheme()
+	theme := style.GetTheme()
 	var parts []string
 
 	// Header with command

internal/ui/messages.go

@@ -9,6 +9,9 @@ import (
 
 	"charm.land/lipgloss/v2"
 	"github.com/indaco/herald"
+
+	"github.com/mark3labs/kit/internal/ui/render"
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // MessageType represents different categories of messages displayed in the UI,
@@ -138,7 +141,7 @@ func newMessageRenderer(width int, debug bool) *MessageRenderer {
 	return &MessageRenderer{
 		width: width,
 		debug: debug,
-		ty:    createTypography(GetTheme()),
+		ty:    createTypography(style.GetTheme()),
 	}
 }
 
@@ -149,12 +152,7 @@ func (r *MessageRenderer) SetWidth(width int) {
 
 // RenderUserMessage renders a user's input message using herald Tip alert
 func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time) UIMessage {
-	if strings.TrimSpace(content) == "" {
-		content = "(empty message)"
-	}
-
-	rendered := r.ty.Tip(content)
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.UserBlock(content, r.width, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      UserMessage,
@@ -166,18 +164,7 @@ func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time)
 
 // RenderAssistantMessage renders an AI assistant's response
 func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage {
-	if strings.TrimSpace(content) == "" {
-		return UIMessage{
-			Type:      AssistantMessage,
-			Content:   "",
-			Height:    0,
-			Timestamp: timestamp,
-		}
-	}
-
-	// Use markdown rendering with Chroma syntax highlighting
-	rendered := toMarkdown(content, r.width-4)
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.AssistantBlock(content, r.width, style.GetTheme())
 
 	return UIMessage{
 		Type:      AssistantMessage,
@@ -191,23 +178,7 @@ func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.
 // as live streaming: muted italic text with margin. This is used when resuming
 // sessions to display saved reasoning content.
 func (r *MessageRenderer) RenderReasoningBlock(content string, timestamp time.Time) UIMessage {
-	if strings.TrimSpace(content) == "" {
-		return UIMessage{
-			Type:      AssistantMessage,
-			Content:   "",
-			Height:    0,
-			Timestamp: timestamp,
-		}
-	}
-
-	theme := GetTheme()
-	// Match live streaming styling: muted italic text
-	// Same as stream.go renderReasoningBlock()
-	lines := strings.Split(strings.TrimRight(content, "\n"), "\n")
-	contentStr := strings.TrimLeft(strings.Join(lines, "\n"), " \t\n")
-	mutedStyle := lipgloss.NewStyle().Foreground(theme.Muted)
-	rendered := mutedStyle.Render(r.ty.Italic(contentStr))
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.ReasoningBlock(content, 0, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      AssistantMessage,
@@ -219,12 +190,7 @@ func (r *MessageRenderer) RenderReasoningBlock(content string, timestamp time.Ti
 
 // RenderSystemMessage renders KIT system messages using herald Note alert
 func (r *MessageRenderer) RenderSystemMessage(content string, timestamp time.Time) UIMessage {
-	if strings.TrimSpace(content) == "" {
-		content = "No content available"
-	}
-
-	rendered := r.ty.Note(content)
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.SystemBlock(content, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      SystemMessage,
@@ -290,8 +256,7 @@ func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timest
 
 // RenderErrorMessage renders error notifications
 func (r *MessageRenderer) RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage {
-	rendered := r.ty.Caution(errorMsg)
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.ErrorBlock(errorMsg, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      ErrorMessage,
@@ -323,16 +288,16 @@ func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 	}
 
 	var icon string
-	iconColor := GetTheme().Success
+	iconColor := style.GetTheme().Success
 	if isError {
 		icon = "×"
-		iconColor = GetTheme().Error
+		iconColor = style.GetTheme().Error
 	} else {
 		icon = "✓"
 	}
 
 	// Style the tool name with color
-	theme := GetTheme()
+	theme := style.GetTheme()
 	nameColor := theme.Info
 	if isError {
 		nameColor = theme.Error
@@ -351,7 +316,7 @@ func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 	if extRd != nil && extRd.RenderBody != nil {
 		body = extRd.RenderBody(toolResult, isError, r.width-8)
 		if body != "" && extRd.BodyMarkdown {
-			body = strings.TrimSuffix(toMarkdown(body, r.width-8), "\n")
+			body = strings.TrimSuffix(style.ToMarkdown(body, r.width-8), "\n")
 		}
 	}
 	if body == "" {
@@ -369,6 +334,12 @@ func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 		body = r.ty.Italic("(no output)")
 	}
 
+	// Wrap all tool errors in a herald Caution alert so the error text
+	// renders inside a contained block instead of spilling into the layout.
+	if isError && strings.TrimSpace(body) != "" {
+		body = r.ty.Alert(herald.AlertCaution, body)
+	}
+
 	// Compose: icon + name + params, then body
 	fullContent := r.ty.Compose(
 		headerLine,
@@ -397,7 +368,7 @@ func (r *MessageRenderer) formatToolResult(toolName, result string) string {
 	if strings.Contains(toolName, "bash") || strings.Contains(toolName, "command") ||
 		strings.Contains(toolName, "shell") {
 		if strings.Contains(result, "<stdout>") || strings.Contains(result, "<stderr>") {
-			return parseBashOutput(result, GetTheme())
+			return parseBashOutput(result, style.GetTheme())
 		}
 	}
 
@@ -405,7 +376,7 @@ func (r *MessageRenderer) formatToolResult(toolName, result string) string {
 }
 
 // createTypography creates a typography instance from theme
-func createTypography(theme Theme) *herald.Typography {
+func createTypography(theme style.Theme) *herald.Typography {
 	return herald.New(
 		herald.WithPalette(herald.ColorPalette{
 			Primary:   theme.Primary,
@@ -437,5 +408,5 @@ func createTypography(theme Theme) *herald.Typography {
 // UpdateTheme refreshes the renderer's typography instance with colors from
 // the current theme. This is called when the user changes themes via /theme.
 func (r *MessageRenderer) UpdateTheme() {
-	r.ty = createTypography(GetTheme())
+	r.ty = createTypography(style.GetTheme())
 }

internal/ui/model_selector.go

@@ -5,9 +5,7 @@ import (
 	"sort"
 	"strings"
 
-	"charm.land/bubbles/v2/key"
 	tea "charm.land/bubbletea/v2"
-	"charm.land/lipgloss/v2"
 
 	"github.com/mark3labs/kit/internal/models"
 )
@@ -29,16 +27,14 @@ type ModelSelectedMsg struct {
 // 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.
+// ModelSelectorComponent is a Bubble Tea component that displays a filterable
+// list of available models as a centered overlay popup. It delegates rendering
+// and keyboard navigation to PopupList and converts results into the
+// ModelSelectedMsg / ModelSelectorCancelledMsg messages expected by AppModel.
 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)
+	popup        *PopupList
+	allModels    []ModelEntry // kept for the custom filter callback
+	currentModel string       // "provider/model" of the active model
 	width        int
 	height       int
 	active       bool
@@ -61,7 +57,22 @@ func NewModelSelector(currentModel string, width, height int) *ModelSelectorComp
 			continue
 		}
 
+		// For the custom provider, skip the built-in "custom" stub when
+		// user-defined models are present — the stub is a fallback for
+		// --provider-url usage and would just clutter the list.
+		userDefinedCustomModels := 0
+		if providerID == "custom" {
+			for modelID := range modelsMap {
+				if modelID != "custom" {
+					userDefinedCustomModels++
+				}
+			}
+		}
+
 		for modelID, info := range modelsMap {
+			if providerID == "custom" && modelID == "custom" && userDefinedCustomModels > 0 {
+				continue
+			}
 			allModels = append(allModels, ModelEntry{
 				Provider:     providerID,
 				ModelID:      modelID,
@@ -80,24 +91,31 @@ func NewModelSelector(currentModel string, width, height int) *ModelSelectorComp
 		return allModels[i].ModelID < allModels[j].ModelID
 	})
 
-	ms := &ModelSelectorComponent{
+	// Build PopupItems from model entries.
+	items := make([]PopupItem, len(allModels))
+	for i, m := range allModels {
+		items[i] = PopupItem{
+			Label:       m.ModelID,
+			Description: fmt.Sprintf("[%s]", m.Provider),
+			Active:      m.Provider+"/"+m.ModelID == currentModel,
+			Meta:        m,
+		}
+	}
+
+	popup := NewPopupList("Model Selector", items, width, height)
+	popup.Subtitle = "Only showing models with configured API keys"
+	popup.FilterFunc = func(query string, allItems []PopupItem) []PopupItem {
+		return filterModels(query, allItems)
+	}
+
+	return &ModelSelectorComponent{
+		popup:        popup,
 		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.
@@ -111,241 +129,94 @@ func (ms *ModelSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case tea.WindowSizeMsg:
 		ms.width = msg.Width
 		ms.height = msg.Height
+		ms.popup.SetSize(msg.Width, 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--
-			}
+		result := ms.popup.HandleKey(msg.String(), msg.Text)
 
-		case key.Matches(msg, key.NewBinding(key.WithKeys("down", "j"))):
-			if ms.cursor < len(ms.filtered)-1 {
-				ms.cursor++
+		if result.Selected != nil {
+			ms.active = false
+			entry := result.Selected.Meta.(ModelEntry)
+			modelStr := entry.Provider + "/" + entry.ModelID
+			return ms, func() tea.Msg {
+				return ModelSelectedMsg{ModelString: modelStr}
 			}
-
-		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()
+		}
+		if result.Cancelled {
+			ms.active = false
+			return ms, func() tea.Msg {
+				return ModelSelectorCancelledMsg{}
 			}
 		}
 	}
 	return ms, nil
 }
 
-// View implements tea.Model.
+// View implements tea.Model — not used for overlay rendering.
+// Use RenderOverlay for the centered overlay approach.
 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")
-	// Adapt help text to terminal width.
-	if ms.width >= 56 {
-		b.WriteString(helpStyle.Render("↑/↓: move  enter: select  esc: cancel  type to filter"))
-	} else if ms.width >= 35 {
-		b.WriteString(helpStyle.Render("↑↓ move  ↵ select  esc  type"))
-	} else {
-		b.WriteString(helpStyle.Render("↑↓ ↵ esc"))
-	}
-	b.WriteString("\n")
-	if ms.width >= 48 {
-		b.WriteString(infoStyle.Render("Only showing models with configured API keys"))
-	} else {
-		b.WriteString(infoStyle.Render("Models with 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, "  ")))
-
-	v := tea.NewView(b.String())
+	// Fallback full-screen rendering (unused when rendered as overlay).
+	v := tea.NewView(ms.popup.RenderCentered(ms.width, ms.height))
 	v.AltScreen = true
-	v.MouseMode = tea.MouseModeCellMotion
-	v.ReportFocus = true
-	v.KeyboardEnhancements = tea.KeyboardEnhancements{
-		ReportEventTypes: true,
-	}
 	return v
 }
 
+// RenderOverlay returns the popup as a centered overlay string, ready to be
+// composited on top of the main content via overlayContent().
+func (ms *ModelSelectorComponent) RenderOverlay(termWidth, termHeight int) string {
+	return ms.popup.RenderCentered(termWidth, termHeight)
+}
+
 // IsActive returns whether the selector is still accepting input.
 func (ms *ModelSelectorComponent) IsActive() bool {
 	return ms.active
 }
 
-// --- Internal helpers ---
+// --- Model-specific fuzzy filter ---
 
-func (ms *ModelSelectorComponent) visibleHeight() int {
-	// Reserve: header(1) + help(1) + info(1) + search(1) + separator(1) + footer(2) = 7.
-	// Minimum 3 entries so the selector is still usable on short terminals.
-	return max(ms.height-7, 3)
-}
+// filterModels scores and filters PopupItems whose Meta is a ModelEntry.
+func filterModels(query string, items []PopupItem) []PopupItem {
+	if query == "" {
+		return items
+	}
+	q := strings.ToLower(query)
 
-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 {
+		item  PopupItem
+		score int
+	}
+	var matches []scored
 
-		type scored struct {
-			entry ModelEntry
-			score int
+	for _, item := range items {
+		entry, ok := item.Meta.(ModelEntry)
+		if !ok {
+			continue
 		}
-		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
+		s := fuzzyScoreModelEntry(q, entry)
+		if s > 0 {
+			matches = append(matches, scored{item: item, score: s})
 		}
 	}
 
-	// Clamp cursor.
-	if ms.cursor >= len(ms.filtered) {
-		ms.cursor = max(len(ms.filtered)-1, 0)
+	sort.Slice(matches, func(i, j int) bool {
+		if matches[i].score != matches[j].score {
+			return matches[i].score > matches[j].score
+		}
+		a := matches[i].item.Meta.(ModelEntry)
+		b := matches[j].item.Meta.(ModelEntry)
+		return a.ModelID < b.ModelID
+	})
+
+	result := make([]PopupItem, len(matches))
+	for i, m := range matches {
+		result[i] = m.item
 	}
+	return result
 }
 
-// fuzzyScoreModel scores a model entry against the search query.
-func (ms *ModelSelectorComponent) fuzzyScoreModel(query string, entry ModelEntry) int {
+// fuzzyScoreModelEntry scores a model entry against the search query.
+func fuzzyScoreModelEntry(query string, entry ModelEntry) int {
 	modelID := strings.ToLower(entry.ModelID)
 	provider := strings.ToLower(entry.Provider)
 	name := strings.ToLower(entry.Name)
@@ -398,67 +269,3 @@ func (ms *ModelSelectorComponent) fuzzyScoreModel(query string, entry ModelEntry
 
 	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
-	activeWidth := 0
-	if entry.Provider+"/"+entry.ModelID == ms.currentModel {
-		active = lipgloss.NewStyle().Foreground(theme.Success).Render(" \u2713")
-		activeWidth = 2 // " ✓"
-	}
-
-	// Truncate model ID and provider tag to fit terminal width.
-	// Layout: cursor(3) + model + " " + provider + active.
-	// Use rune length for display-width accuracy (the "…" suffix is 1 rune / 1 column).
-	const cursorWidth = 3
-	available := max(ms.width-cursorWidth-activeWidth-1, 10) // 1 for space between model and provider
-	provDisplayLen := len([]rune(providerStr))
-	modelDisplayLen := len([]rune(modelStr))
-
-	if modelDisplayLen+1+provDisplayLen > available {
-		// Prioritize model name — truncate it, but keep provider visible.
-		maxModel := max(available-provDisplayLen-1, 6)
-		if maxModel < modelDisplayLen {
-			if maxModel > 3 {
-				runes := []rune(modelStr)
-				modelStr = string(runes[:maxModel-1]) + "…"
-			} else {
-				runes := []rune(modelStr)
-				modelStr = string(runes[:maxModel])
-			}
-		}
-		// If provider itself is too long, drop it.
-		modelDisplayLen = len([]rune(modelStr))
-		if modelDisplayLen+1+provDisplayLen > available {
-			providerStr = ""
-		}
-	}
-
-	// 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)
-
-	result := cursor + modelStyle.Render(modelStr)
-	if providerStr != "" {
-		result += " " + providerStyle.Render(providerStr)
-	}
-	return result + active
-}

internal/ui/model_test.go

@@ -2,11 +2,13 @@ package ui
 
 import (
 	"errors"
+	"strings"
 	"testing"
 
 	tea "charm.land/bubbletea/v2"
 	"github.com/mark3labs/kit/internal/app"
 	"github.com/mark3labs/kit/internal/session"
+	"github.com/mark3labs/kit/internal/ui/core"
 	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
@@ -80,6 +82,11 @@ func (s *stubAppController) Steer(prompt string) int {
 	return s.queueLen
 }
 
+func (s *stubAppController) SteerWithFiles(prompt string, _ []kit.LLMFilePart) int {
+	s.runCalls = append(s.runCalls, prompt)
+	return s.queueLen
+}
+
 // --------------------------------------------------------------------------
 // Stub child components
 // --------------------------------------------------------------------------
@@ -87,7 +94,6 @@ func (s *stubAppController) Steer(prompt string) int {
 // stubStreamComponent satisfies streamComponentIface without rendering anything.
 type stubStreamComponent struct {
 	resetCalled     int
-	height          int
 	lastMsg         tea.Msg
 	renderedContent string // returned by GetRenderedContent
 }
@@ -99,9 +105,7 @@ func (s *stubStreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 }
 func (s *stubStreamComponent) View() tea.View             { return tea.NewView("") }
 func (s *stubStreamComponent) Reset()                     { s.resetCalled++; s.renderedContent = "" }
-func (s *stubStreamComponent) SetHeight(h int)            { s.height = h }
 func (s *stubStreamComponent) GetRenderedContent() string { return s.renderedContent }
-func (s *stubStreamComponent) ConsumeOverflow() string    { return "" }
 func (s *stubStreamComponent) SpinnerView() string        { return "" }
 func (s *stubStreamComponent) SetThinkingVisible(bool)    {}
 func (s *stubStreamComponent) HasReasoning() bool         { return false }
@@ -136,6 +140,8 @@ func newTestAppModel(ctrl AppController) (*AppModel, *stubStreamComponent, *stub
 		width:                 80,
 		height:                24,
 		streamingBashMaxLines: 50, // Initialize buffer cap like NewAppModel does
+		scrollList:            NewScrollList(80, 20),
+		messages:              []MessageItem{},
 	}
 	return m, stream, input
 }
@@ -168,7 +174,7 @@ func TestStateTransition_InputToWorking(t *testing.T) {
 		t.Fatalf("expected stateInput, got %v", m.state)
 	}
 
-	m = sendMsg(m, submitMsg{Text: "hello"})
+	m = sendMsg(m, core.SubmitMsg{Text: "hello"})
 
 	if m.state != stateWorking {
 		t.Fatalf("expected stateWorking after submitMsg, got %v", m.state)
@@ -356,7 +362,7 @@ func TestESCCancel_timerExpiry(t *testing.T) {
 	m.state = stateWorking
 	m.canceling = true
 
-	m = sendMsg(m, cancelTimerExpiredMsg{})
+	m = sendMsg(m, core.CancelTimerExpiredMsg{})
 
 	if m.canceling {
 		t.Fatal("expected canceling=false after timer expiry")
@@ -409,7 +415,7 @@ func TestQueuedMessages_storedOnQueuedSubmit(t *testing.T) {
 	m, _, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	_, cmd := m.Update(submitMsg{Text: "queued prompt"})
+	_, cmd := m.Update(core.SubmitMsg{Text: "queued prompt"})
 
 	if len(m.queuedMessages) != 1 {
 		t.Fatalf("expected 1 queued message, got %d", len(m.queuedMessages))
@@ -417,7 +423,7 @@ func TestQueuedMessages_storedOnQueuedSubmit(t *testing.T) {
 	if m.queuedMessages[0] != "queued prompt" {
 		t.Fatalf("expected queued message text 'queued prompt', got %q", m.queuedMessages[0])
 	}
-	// Should NOT produce a tea.Println cmd (message is anchored, not in scrollback).
+	// Should NOT flush (message is anchored in ScrollList).
 	if cmd != nil {
 		t.Fatal("expected nil cmd for queued submit (message should not print to scrollback)")
 	}
@@ -507,19 +513,19 @@ func TestWindowResize_propagatesToStream(t *testing.T) {
 // sets the stream height after a resize.
 func TestWindowResize_distributeHeight(t *testing.T) {
 	ctrl := &stubAppController{}
-	m, stream, _ := newTestAppModel(ctrl)
+	m, _, _ := newTestAppModel(ctrl)
 
-	// With height=30, stream height = 30 - 1 (separator) - 9 (input) - 1 (statusBar) = 19
+	// With height=30, scroll height = 30 - 1 (separator) - 9 (input) - 1 (statusBar) = 19
 	m = sendMsg(m, tea.WindowSizeMsg{Width: 80, Height: 30})
 	_ = m
 
-	if stream.height != 19 {
-		t.Fatalf("expected stream height=19, got %d", stream.height)
+	if m.scrollList.height != 19 {
+		t.Fatalf("expected scroll list height=19, got %d", m.scrollList.height)
 	}
 }
 
 // --------------------------------------------------------------------------
-// tea.Println on step complete
+// Step complete behavior
 // --------------------------------------------------------------------------
 
 // TestStepComplete_preservesStreamContent verifies that StepCompleteEvent
@@ -552,65 +558,87 @@ func TestStepComplete_noStreamContent_noCmd(t *testing.T) {
 	}
 }
 
-// TestSubmitMsg_printsUserMessage verifies that submitMsg produces a tea.Println
-// cmd for the user message.
+// TestSubmitMsg_printsUserMessage verifies that submitMsg adds the user message
+// to the ScrollList messages and triggers a layout update.
 func TestSubmitMsg_printsUserMessage(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
 
-	_, cmd := m.Update(submitMsg{Text: "user query"})
+	m = sendMsg(m, core.SubmitMsg{Text: "user query"})
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd (tea.Println) for user message on submitMsg")
+	// In alt screen mode, user messages are added to the in-memory ScrollList
+	// rather than printed separately. Verify the message was added.
+	found := false
+	for _, msg := range m.messages {
+		if tm, ok := msg.(*TextMessageItem); ok && tm.role == "user" && tm.content == "user query" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("expected user message 'user query' in ScrollList messages")
 	}
 }
 
-// TestToolCallStarted_flushesOnly verifies that ToolCallStartedEvent flushes
-// accumulated stream content but does NOT print a tool call block (the unified
-// block is printed later on ToolResultEvent).
+// TestToolCallStarted_flushesOnly verifies that ToolCallStartedEvent marks
+// any active StreamingMessageItem as complete and resets the stream.
 func TestToolCallStarted_flushesOnly(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, stream, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	// With no stream content, flush returns nil → cmd should be nil.
-	_, cmd := m.Update(app.ToolCallStartedEvent{
+	// With no stream content, nothing should change.
+	initialCount := len(m.messages)
+	m = sendMsg(m, app.ToolCallStartedEvent{
 		ToolName: "bash",
 		ToolArgs: `{"cmd":"ls"}`,
 	})
 
-	if cmd != nil {
-		t.Fatal("expected nil cmd on ToolCallStartedEvent with no stream content")
+	if len(m.messages) != initialCount {
+		t.Fatal("expected no new messages on ToolCallStartedEvent with no stream content")
 	}
 
-	// With stream content, flush returns tea.Println → cmd should be non-nil.
+	// Simulate a StreamingMessageItem already in messages (as if appendStreamingChunk was called)
+	// plus the stream component having rendered content.
+	streamItem := NewStreamingMessageItem("stream-1", "assistant", "test-model")
+	streamItem.AppendChunk("partial text")
+	m.messages = append(m.messages, streamItem)
 	stream.renderedContent = "partial text"
-	_, cmd = m.Update(app.ToolCallStartedEvent{
+
+	_ = sendMsg(m, app.ToolCallStartedEvent{
 		ToolName: "bash",
 		ToolArgs: `{"cmd":"ls"}`,
 	})
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd on ToolCallStartedEvent with stream content to flush")
+	// The StreamingMessageItem should have been marked complete.
+	if streamItem.streaming {
+		t.Fatal("expected StreamingMessageItem to be marked complete after ToolCallStartedEvent")
+	}
+	// Stream should have been reset.
+	if stream.resetCalled == 0 {
+		t.Fatal("expected stream.Reset() to be called")
 	}
 }
 
-// TestToolResult_printsAndStartsSpinner verifies that ToolResultEvent produces
-// a non-nil cmd and the stream receives a SpinnerEvent.
+// TestToolResult_printsAndStartsSpinner verifies that ToolResultEvent adds
+// the tool result to the ScrollList and the stream receives a SpinnerEvent.
 func TestToolResult_printsAndStartsSpinner(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, stream, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	_, cmd := m.Update(app.ToolResultEvent{
+	initialCount := len(m.messages)
+
+	m = sendMsg(m, app.ToolResultEvent{
 		ToolName: "bash",
 		ToolArgs: "{}",
 		Result:   "output",
 		IsError:  false,
 	})
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd on ToolResultEvent")
+	// Tool result should have been added to ScrollList messages.
+	if len(m.messages) <= initialCount {
+		t.Fatal("expected tool result message added to ScrollList")
 	}
 	// Stream should have received a SpinnerEvent to start spinner for next LLM call.
 	if stream.lastMsg == nil {
@@ -622,7 +650,7 @@ func TestToolResult_printsAndStartsSpinner(t *testing.T) {
 }
 
 // TestToolOutputEvent_accumulatesBashOutput verifies that ToolOutputEvent
-// accumulates stdout and stderr lines into the streaming bash output buffers.
+// accumulates stdout and stderr lines into a StreamingBashOutputItem in the ScrollList.
 func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
@@ -636,11 +664,23 @@ func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 		IsStderr:   false,
 	})
 
-	if len(m.streamingBashOutput) != 1 || m.streamingBashOutput[0] != "line one\n" {
-		t.Fatalf("expected streamingBashOutput=['line one\\n'], got %v", m.streamingBashOutput)
+	// Should have created a StreamingBashOutputItem in messages.
+	var bashItem *StreamingBashOutputItem
+	for _, msg := range m.messages {
+		if item, ok := msg.(*StreamingBashOutputItem); ok {
+			bashItem = item
+			break
+		}
 	}
-	if len(m.streamingBashStderr) != 0 {
-		t.Fatalf("expected empty streamingBashStderr, got %v", m.streamingBashStderr)
+	if bashItem == nil {
+		t.Fatal("expected StreamingBashOutputItem in messages after ToolOutputEvent")
+		return
+	}
+	if len(bashItem.stdoutLines) != 1 || bashItem.stdoutLines[0] != "line one\n" {
+		t.Fatalf("expected stdout=['line one\\n'], got %v", bashItem.stdoutLines)
+	}
+	if len(bashItem.stderrLines) != 0 {
+		t.Fatalf("expected empty stderr, got %v", bashItem.stderrLines)
 	}
 
 	// Send another stdout chunk.
@@ -651,8 +691,15 @@ func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 		IsStderr:   false,
 	})
 
-	if len(m.streamingBashOutput) != 2 {
-		t.Fatalf("expected 2 stdout lines, got %d", len(m.streamingBashOutput))
+	// Re-find the bash item (same item, updated)
+	bashItem = nil
+	for _, msg := range m.messages {
+		if item, ok := msg.(*StreamingBashOutputItem); ok {
+			bashItem = item
+		}
+	}
+	if bashItem == nil || len(bashItem.stdoutLines) != 2 {
+		t.Fatalf("expected 2 stdout lines, got %d", len(bashItem.stdoutLines))
 	}
 
 	// Send stderr chunk.
@@ -663,11 +710,17 @@ func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 		IsStderr:   true,
 	})
 
-	if len(m.streamingBashStderr) != 1 {
-		t.Fatalf("expected 1 stderr line, got %d", len(m.streamingBashStderr))
+	bashItem = nil
+	for _, msg := range m.messages {
+		if item, ok := msg.(*StreamingBashOutputItem); ok {
+			bashItem = item
+		}
 	}
-	if m.streamingBashStderr[0] != "error: something failed\n" {
-		t.Fatalf("expected stderr 'error: something failed\\n', got %q", m.streamingBashStderr[0])
+	if bashItem == nil || len(bashItem.stderrLines) != 1 {
+		t.Fatalf("expected 1 stderr line, got %d", len(bashItem.stderrLines))
+	}
+	if bashItem.stderrLines[0] != "error: something failed\n" {
+		t.Fatalf("expected stderr 'error: something failed\\n', got %q", bashItem.stderrLines[0])
 	}
 }
 
@@ -749,16 +802,19 @@ func TestToolCallStarted_nonBashTool_doesNotSetCommand(t *testing.T) {
 }
 
 // TestStepError_printCmd verifies that StepErrorEvent with a non-nil error
-// produces a non-nil cmd (the tea.Println call for the error message).
+// adds an error message to the ScrollList.
 func TestStepError_printCmd(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	_, cmd := m.Update(app.StepErrorEvent{Err: errors.New("agent failed")})
+	initialCount := len(m.messages)
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd (tea.Println) on StepErrorEvent with error")
+	m = sendMsg(m, app.StepErrorEvent{Err: errors.New("agent failed")})
+
+	// Error should have been added to ScrollList messages.
+	if len(m.messages) <= initialCount {
+		t.Fatal("expected error message added to ScrollList on StepErrorEvent")
 	}
 }
 
@@ -828,7 +884,7 @@ func TestSubmit_duringWorking_stays(t *testing.T) {
 	m, _, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	m = sendMsg(m, submitMsg{Text: "queued prompt"})
+	m = sendMsg(m, core.SubmitMsg{Text: "queued prompt"})
 
 	if m.state != stateWorking {
 		t.Fatalf("expected stateWorking to persist after submitMsg during working, got %v", m.state)
@@ -837,3 +893,107 @@ func TestSubmit_duringWorking_stays(t *testing.T) {
 		t.Fatalf("expected Run('queued prompt') called, got %v", ctrl.runCalls)
 	}
 }
+
+// --------------------------------------------------------------------------
+// truncateMessageForBlock
+// --------------------------------------------------------------------------
+
+// TestTruncateMessageForBlock_shortMessage verifies that short messages are
+// returned unchanged.
+func TestTruncateMessageForBlock_shortMessage(t *testing.T) {
+	msg := "hello world"
+	got := truncateMessageForBlock(msg, 3, 80)
+	if got != msg {
+		t.Fatalf("expected unchanged message, got %q", got)
+	}
+}
+
+// TestTruncateMessageForBlock_exactLines verifies that a message with exactly
+// maxLines hard lines is returned unchanged.
+func TestTruncateMessageForBlock_exactLines(t *testing.T) {
+	msg := "line1\nline2\nline3"
+	got := truncateMessageForBlock(msg, 3, 80)
+	if got != msg {
+		t.Fatalf("expected unchanged message, got %q", got)
+	}
+}
+
+// TestTruncateMessageForBlock_tooManyLines verifies that messages exceeding
+// maxLines are truncated with an ellipsis.
+func TestTruncateMessageForBlock_tooManyLines(t *testing.T) {
+	msg := "line1\nline2\nline3\nline4\nline5"
+	got := truncateMessageForBlock(msg, 3, 80)
+	want := "line1\nline2\nline3…"
+	if got != want {
+		t.Fatalf("expected %q, got %q", want, got)
+	}
+}
+
+// TestTruncateMessageForBlock_longWrappingLine verifies that a single long
+// line that would wrap beyond maxLines is truncated.
+func TestTruncateMessageForBlock_longWrappingLine(t *testing.T) {
+	// 100 chars at width 20 = 5 visual lines, exceeds maxLines=3
+	msg := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+	got := truncateMessageForBlock(msg, 3, 20)
+	// Should be truncated to 3*20=60 runes + "…"
+	if len([]rune(got)) != 61 { // 60 runes + "…"
+		t.Fatalf("expected 61 runes (60 + ellipsis), got %d runes: %q", len([]rune(got)), got)
+	}
+	if got[len(got)-3:] != "…" { // "…" is 3 bytes in UTF-8
+		t.Fatal("expected trailing ellipsis")
+	}
+}
+
+// TestTruncateMessageForBlock_emptyMessage verifies that empty messages are
+// returned unchanged.
+func TestTruncateMessageForBlock_emptyMessage(t *testing.T) {
+	got := truncateMessageForBlock("", 3, 80)
+	if got != "" {
+		t.Fatalf("expected empty string, got %q", got)
+	}
+}
+
+// TestTruncateMessageForBlock_mixedWrapAndHardLines verifies truncation when
+// some hard lines wrap and the total exceeds maxLines.
+func TestTruncateMessageForBlock_mixedWrapAndHardLines(t *testing.T) {
+	// First line: 40 chars at width 20 = 2 visual lines
+	// Second line: "short" = 1 visual line (total: 3, exactly at limit)
+	// Third line: would exceed
+	msg := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\nshort\nextra"
+	got := truncateMessageForBlock(msg, 3, 20)
+	want := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\nshort…"
+	if got != want {
+		t.Fatalf("expected %q, got %q", want, got)
+	}
+}
+
+// TestRenderQueuedMessages_truncatesLongMessages verifies that the rendered
+// queued message view truncates long messages instead of showing them in full.
+func TestRenderQueuedMessages_truncatesLongMessages(t *testing.T) {
+	ctrl := &stubAppController{}
+	m, _, _ := newTestAppModel(ctrl)
+	m.width = 80
+
+	// Queue a very long message (20 lines).
+	var b strings.Builder
+	for i := range 20 {
+		if i > 0 {
+			b.WriteByte('\n')
+		}
+		b.WriteString("This is a long line of text for testing purposes")
+	}
+	m.queuedMessages = []string{b.String()}
+
+	rendered := m.renderQueuedMessages()
+	if rendered == "" {
+		t.Fatal("expected non-empty rendered output")
+	}
+
+	// The full message would be ~20+ lines. With truncation to 3 content
+	// lines + badge + padding, it should be much shorter.
+	lines := len(strings.Split(rendered, "\n"))
+	// 3 content lines + 1 badge + 2 padding + border overhead ≈ ~7 lines max
+	if lines > 10 {
+		t.Fatalf("expected truncated output to be ≤10 lines, got %d lines", lines)
+	}
+}

internal/ui/overlay.go

@@ -6,6 +6,8 @@ import (
 
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // ---------------------------------------------------------------------------
@@ -133,7 +135,7 @@ func (o *overlayDialog) handleKey(msg tea.KeyPressMsg) (*overlayResult, tea.Cmd)
 // composition. The dialog is a bordered box centered (or anchored)
 // horizontally within the terminal width.
 func (o *overlayDialog) Render() string {
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	// Calculate dialog dimensions, clamped to terminal bounds.
 	termW := max(o.width, 10)
@@ -157,7 +159,7 @@ func (o *overlayDialog) Render() string {
 	// Render body text (potentially as markdown).
 	bodyText := o.content
 	if o.markdown {
-		bodyText = toMarkdown(bodyText, innerWidth)
+		bodyText = style.ToMarkdown(bodyText, innerWidth)
 	}
 	bodyText = strings.TrimRight(bodyText, "\n")
 

internal/ui/popup_list.go

@@ -0,0 +1,501 @@
+package ui
+
+import (
+	"fmt"
+	"strings"
+
+	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
+)
+
+// PopupItem represents a single entry in a PopupList. The component renders
+// Label as the primary text and Description as secondary text to its right.
+// The Active flag renders a checkmark to indicate the currently-active item
+// (e.g. the current model). Meta is opaque caller data returned on selection.
+type PopupItem struct {
+	Label       string // primary display text
+	Description string // secondary text (shown right of label)
+	Active      bool   // true → render checkmark indicator
+	Meta        any    // opaque data returned on selection
+}
+
+// PopupList is a generic, themed, scrollable fuzzy-find popup list. It is
+// rendered as a centered overlay on top of the normal TUI layout and can be
+// reused by any feature that needs a selection popup (slash commands, model
+// selector, session picker, extension-provided lists, etc.).
+//
+// The caller is responsible for:
+//   - Building the initial item list
+//   - Providing a fuzzy-filter callback (or nil for substring matching)
+//   - Handling the result when the user selects or cancels
+//
+// Navigation: up/down to move, enter to select, esc to cancel, type to filter.
+type PopupList struct {
+	// Title shown at the top of the popup.
+	Title string
+	// Subtitle shown below the title (dimmed).
+	Subtitle string
+	// FooterHint overrides the default keyboard-hint footer.
+	FooterHint string
+
+	allItems []PopupItem // full unfiltered list
+	filtered []PopupItem // subset matching the current search
+	cursor   int
+	search   string
+
+	// FilterFunc is called with (query, allItems) and should return the
+	// filtered+scored subset. When nil, a default substring match is used.
+	FilterFunc func(query string, items []PopupItem) []PopupItem
+
+	width      int
+	height     int
+	maxVisible int // max items visible at once (0 = auto from height)
+	showSearch bool
+}
+
+// PopupResult is returned by HandleKey to tell the caller what happened.
+type PopupResult struct {
+	// Selected is non-nil when the user pressed Enter on an item.
+	Selected *PopupItem
+	// Cancelled is true when the user pressed Esc with no search text.
+	Cancelled bool
+	// Changed is true when the search or cursor moved (caller should re-render).
+	Changed bool
+}
+
+// NewPopupList creates a new popup list with the given items and dimensions.
+func NewPopupList(title string, items []PopupItem, width, height int) *PopupList {
+	p := &PopupList{
+		Title:      title,
+		allItems:   items,
+		filtered:   items,
+		width:      width,
+		height:     height,
+		showSearch: true,
+	}
+	// Position cursor on the active item if one exists.
+	for i, item := range p.filtered {
+		if item.Active {
+			p.cursor = i
+			break
+		}
+	}
+	return p
+}
+
+// SetSize updates the popup dimensions (e.g. on window resize).
+func (p *PopupList) SetSize(width, height int) {
+	p.width = width
+	p.height = height
+}
+
+// visibleCount returns the number of items visible at once.
+func (p *PopupList) visibleCount() int {
+	if p.maxVisible > 0 {
+		return p.maxVisible
+	}
+	// Reserve: title(1) + subtitle(1) + search(1) + separator(1) + footer(2) + border(2) + padding(2) = 10
+	overhead := 8
+	if p.Subtitle != "" {
+		overhead++
+	}
+	if p.showSearch {
+		overhead += 2 // search line + separator
+	}
+	return max(p.height/2-overhead, 3)
+}
+
+// HandleKey processes a single key event and returns the result. The caller
+// should inspect PopupResult to decide whether to re-render, close the popup,
+// or act on a selection.
+//
+// keyName is the Bubble Tea key string (e.g. "up", "down", "enter", "esc").
+// keyText is the printable text for character keys (e.g. "a", "1").
+func (p *PopupList) HandleKey(keyName, keyText string) PopupResult {
+	switch keyName {
+	case "up":
+		if p.cursor > 0 {
+			p.cursor--
+			return PopupResult{Changed: true}
+		}
+		return PopupResult{}
+
+	case "down":
+		if p.cursor < len(p.filtered)-1 {
+			p.cursor++
+			return PopupResult{Changed: true}
+		}
+		return PopupResult{}
+
+	case "pgup":
+		p.cursor -= p.visibleCount()
+		if p.cursor < 0 {
+			p.cursor = 0
+		}
+		return PopupResult{Changed: true}
+
+	case "pgdown":
+		p.cursor += p.visibleCount()
+		if p.cursor >= len(p.filtered) {
+			p.cursor = max(len(p.filtered)-1, 0)
+		}
+		return PopupResult{Changed: true}
+
+	case "home":
+		p.cursor = 0
+		return PopupResult{Changed: true}
+
+	case "end":
+		p.cursor = max(len(p.filtered)-1, 0)
+		return PopupResult{Changed: true}
+
+	case "enter":
+		if p.cursor < len(p.filtered) {
+			item := p.filtered[p.cursor]
+			return PopupResult{Selected: &item}
+		}
+		return PopupResult{}
+
+	case "esc":
+		if p.search != "" {
+			p.search = ""
+			p.rebuildFiltered()
+			return PopupResult{Changed: true}
+		}
+		return PopupResult{Cancelled: true}
+
+	case "backspace":
+		if len(p.search) > 0 {
+			p.search = p.search[:len(p.search)-1]
+			p.rebuildFiltered()
+			return PopupResult{Changed: true}
+		}
+		return PopupResult{}
+
+	default:
+		// Printable character → append to search.
+		if keyText != "" && len(keyText) == 1 {
+			ch := keyText[0]
+			if ch >= 32 && ch < 127 {
+				p.search += string(ch)
+				p.rebuildFiltered()
+				return PopupResult{Changed: true}
+			}
+		}
+		return PopupResult{}
+	}
+}
+
+// Render returns the styled popup content (bordered box) ready to be placed
+// as a centered overlay via lipgloss.Place + overlayContent.
+func (p *PopupList) Render() string {
+	theme := style.GetTheme()
+	popupWidth := max(min(p.width-4, 80), 20)
+	popupBg := theme.Background
+
+	popupStyle := lipgloss.NewStyle().
+		Border(lipgloss.RoundedBorder()).
+		BorderForeground(theme.Primary).
+		Background(popupBg).
+		Padding(1, 2).
+		Width(popupWidth).
+		MarginBottom(1)
+
+	// Inner content width: popup minus border (2) and horizontal padding (4).
+	innerWidth := max(popupWidth-6, 10)
+
+	var b strings.Builder
+
+	// Title.
+	titleStyle := lipgloss.NewStyle().
+		Bold(true).
+		Foreground(theme.Accent).
+		Background(popupBg).
+		Width(innerWidth)
+	b.WriteString(titleStyle.Render(p.Title))
+	b.WriteString("\n")
+
+	// Subtitle.
+	if p.Subtitle != "" {
+		subtitleStyle := lipgloss.NewStyle().
+			Foreground(theme.Muted).
+			Background(popupBg).
+			Width(innerWidth)
+		b.WriteString(subtitleStyle.Render(p.Subtitle))
+		b.WriteString("\n")
+	}
+
+	// Search input.
+	if p.showSearch {
+		searchStyle := lipgloss.NewStyle().
+			Foreground(theme.Info).
+			Background(popupBg).
+			Width(innerWidth)
+		if p.search != "" {
+			b.WriteString(searchStyle.Render(fmt.Sprintf("> %s", p.search)))
+		} else {
+			b.WriteString(searchStyle.Render("> "))
+		}
+		b.WriteString("\n")
+
+		// Separator.
+		sepStyle := lipgloss.NewStyle().
+			Foreground(theme.Muted).
+			Background(popupBg)
+		b.WriteString(sepStyle.Render(strings.Repeat("─", innerWidth)))
+		b.WriteString("\n")
+	}
+
+	// Item list.
+	normalItemBg := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.Text).
+		Width(innerWidth).
+		Padding(0, 1)
+
+	selectedItemBg := lipgloss.NewStyle().
+		Background(theme.Primary).
+		Foreground(theme.Background).
+		Width(innerWidth).
+		Padding(0, 1).
+		Bold(true)
+
+	scrollStyle := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.VeryMuted).
+		Width(innerWidth).
+		Padding(0, 1)
+
+	vis := p.visibleCount()
+	var items []string
+
+	if len(p.filtered) == 0 {
+		emptyStyle := lipgloss.NewStyle().
+			Foreground(theme.Muted).
+			Background(popupBg).
+			Width(innerWidth).
+			Padding(0, 1)
+		if p.search != "" {
+			items = append(items, emptyStyle.Render("No matches for \""+p.search+"\""))
+		} else {
+			items = append(items, emptyStyle.Render("No items"))
+		}
+	} else {
+		startIdx := 0
+		if p.cursor >= vis {
+			startIdx = p.cursor - vis + 1
+		}
+		endIdx := min(startIdx+vis, len(p.filtered))
+
+		if startIdx > 0 {
+			items = append(items, scrollStyle.Render("  ↑ more above"))
+		}
+
+		for i := startIdx; i < endIdx; i++ {
+			entry := p.filtered[i]
+			isCursor := i == p.cursor
+
+			itemStyle := normalItemBg
+			if isCursor {
+				itemStyle = selectedItemBg
+			}
+
+			// Build indicator.
+			var indicator string
+			if isCursor {
+				indicator = "> "
+			} else {
+				indicator = "  "
+			}
+
+			// Build content: indicator + label + description + active checkmark.
+			content := p.renderItemContent(indicator, entry, innerWidth, isCursor)
+			items = append(items, itemStyle.Render(content))
+		}
+
+		if endIdx < len(p.filtered) {
+			items = append(items, scrollStyle.Render("  ↓ more below"))
+		}
+	}
+
+	content := b.String() + strings.Join(items, "\n")
+
+	// Footer with count and keyboard hints.
+	var footerParts []string
+	footerParts = append(footerParts, fmt.Sprintf("(%d/%d)", p.cursor+1, len(p.filtered)))
+
+	footerHint := p.FooterHint
+	if footerHint == "" {
+		if innerWidth >= 50 {
+			footerHint = "↑↓ navigate • enter select • esc cancel • type to filter"
+		} else if innerWidth >= 30 {
+			footerHint = "↑↓ nav • ↵ select • esc"
+		} else {
+			footerHint = "↑↓ ↵ esc"
+		}
+	}
+	footerParts = append(footerParts, footerHint)
+
+	footer := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.VeryMuted).
+		Italic(true).
+		Render(strings.Join(footerParts, "  "))
+
+	return popupStyle.Render(content + "\n\n" + footer)
+}
+
+// RenderCentered returns the popup placed at the center of a termWidth×termHeight
+// canvas, ready to be composed with overlayContent().
+func (p *PopupList) RenderCentered(termWidth, termHeight int) string {
+	popupContent := p.Render()
+	return lipgloss.Place(
+		termWidth,
+		termHeight,
+		lipgloss.Center,
+		lipgloss.Center,
+		popupContent,
+	)
+}
+
+// IsSearching returns true when the search input is non-empty.
+func (p *PopupList) IsSearching() bool {
+	return p.search != ""
+}
+
+// SelectedItem returns the item under the cursor, or nil if the list is empty.
+func (p *PopupList) SelectedItem() *PopupItem {
+	if p.cursor < len(p.filtered) {
+		item := p.filtered[p.cursor]
+		return &item
+	}
+	return nil
+}
+
+// --- Internal helpers ---
+
+func (p *PopupList) rebuildFiltered() {
+	if p.FilterFunc != nil {
+		p.filtered = p.FilterFunc(p.search, p.allItems)
+	} else {
+		p.filtered = defaultFilter(p.search, p.allItems)
+	}
+	// Clamp cursor.
+	if p.cursor >= len(p.filtered) {
+		p.cursor = max(len(p.filtered)-1, 0)
+	}
+}
+
+// defaultFilter is a simple case-insensitive substring + fuzzy character match.
+func defaultFilter(query string, items []PopupItem) []PopupItem {
+	if query == "" {
+		return items
+	}
+	q := strings.ToLower(query)
+	type scored struct {
+		item  PopupItem
+		score int
+	}
+	var matches []scored
+	for _, item := range items {
+		label := strings.ToLower(item.Label)
+		desc := strings.ToLower(item.Description)
+
+		var s int
+		switch {
+		case label == q:
+			s = 1000
+		case strings.HasPrefix(label, q):
+			s = 800 - len(label) + len(q)
+		case strings.Contains(label, q):
+			s = 600
+		case strings.Contains(desc, q):
+			s = 400
+		default:
+			s = fuzzyCharacterMatch(q, label)
+		}
+		if s > 0 {
+			matches = append(matches, scored{item: item, score: s})
+		}
+	}
+
+	// Sort by score descending, then alphabetically by label.
+	for i := 0; i < len(matches)-1; i++ {
+		for j := i + 1; j < len(matches); j++ {
+			if matches[j].score > matches[i].score ||
+				(matches[j].score == matches[i].score && matches[j].item.Label < matches[i].item.Label) {
+				matches[i], matches[j] = matches[j], matches[i]
+			}
+		}
+	}
+
+	result := make([]PopupItem, len(matches))
+	for i, m := range matches {
+		result[i] = m.item
+	}
+	return result
+}
+
+// renderItemContent builds the display string for a single item row.
+func (p *PopupList) renderItemContent(indicator string, entry PopupItem, innerWidth int, isCursor bool) string {
+	theme := style.GetTheme()
+
+	// Reserve space: indicator(2) + potential checkmark(2)
+	activeWidth := 0
+	if entry.Active {
+		activeWidth = 2
+	}
+	available := max(innerWidth-2-activeWidth, 6) // 2 for indicator, already included
+
+	label := entry.Label
+	desc := entry.Description
+
+	if desc != "" {
+		// Two-column layout: label + description.
+		descWidth := len([]rune(desc)) + 1 // 1 space gap
+		labelMax := max(available-descWidth, available*2/3)
+		if len([]rune(label)) > labelMax && labelMax > 3 {
+			runes := []rune(label)
+			label = string(runes[:labelMax-1]) + "…"
+		}
+		labelDisplayLen := len([]rune(label))
+
+		// If label + desc don't fit, truncate or drop desc.
+		if labelDisplayLen+1+len([]rune(desc)) > available {
+			remaining := available - labelDisplayLen - 1
+			if remaining >= 4 {
+				runes := []rune(desc)
+				if len(runes) > remaining {
+					desc = string(runes[:remaining-1]) + "…"
+				}
+			} else {
+				desc = ""
+			}
+		}
+	} else {
+		// Single column: just the label.
+		if len([]rune(label)) > available && available > 3 {
+			runes := []rune(label)
+			label = string(runes[:available-1]) + "…"
+		}
+	}
+
+	result := indicator + label
+	if desc != "" {
+		descStyle := lipgloss.NewStyle().Foreground(theme.Muted)
+		if isCursor {
+			// When selected, use a dimmer foreground that still contrasts with Primary bg.
+			descStyle = lipgloss.NewStyle().Foreground(theme.Background)
+		}
+		result += " " + descStyle.Render(desc)
+	}
+	if entry.Active {
+		checkStyle := lipgloss.NewStyle().Foreground(theme.Success)
+		if isCursor {
+			checkStyle = lipgloss.NewStyle().Foreground(theme.Background)
+		}
+		result += checkStyle.Render(" ✓")
+	}
+	return result
+}

internal/ui/popup_list_test.go

@@ -0,0 +1,297 @@
+package ui
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestPopupList_NewPositionsCursorOnActiveItem(t *testing.T) {
+	items := []PopupItem{
+		{Label: "alpha"},
+		{Label: "beta"},
+		{Label: "gamma", Active: true},
+		{Label: "delta"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+
+	if p.cursor != 2 {
+		t.Errorf("expected cursor on active item (index 2), got %d", p.cursor)
+	}
+}
+
+func TestPopupList_HandleKey_Navigation(t *testing.T) {
+	items := []PopupItem{
+		{Label: "alpha"},
+		{Label: "beta"},
+		{Label: "gamma"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+
+	// Initial cursor at 0.
+	if p.cursor != 0 {
+		t.Fatalf("expected cursor 0, got %d", p.cursor)
+	}
+
+	// Down → 1.
+	res := p.HandleKey("down", "")
+	if !res.Changed || p.cursor != 1 {
+		t.Errorf("down: changed=%v cursor=%d", res.Changed, p.cursor)
+	}
+
+	// Down → 2.
+	p.HandleKey("down", "")
+	if p.cursor != 2 {
+		t.Errorf("expected cursor 2, got %d", p.cursor)
+	}
+
+	// Down at end → stays at 2.
+	res = p.HandleKey("down", "")
+	if p.cursor != 2 {
+		t.Errorf("down at end: expected cursor 2, got %d", p.cursor)
+	}
+
+	// Up → 1.
+	res = p.HandleKey("up", "")
+	if !res.Changed || p.cursor != 1 {
+		t.Errorf("up: changed=%v cursor=%d", res.Changed, p.cursor)
+	}
+
+	// Home → 0.
+	p.HandleKey("home", "")
+	if p.cursor != 0 {
+		t.Errorf("home: expected cursor 0, got %d", p.cursor)
+	}
+
+	// End → 2.
+	p.HandleKey("end", "")
+	if p.cursor != 2 {
+		t.Errorf("end: expected cursor 2, got %d", p.cursor)
+	}
+}
+
+func TestPopupList_HandleKey_Search(t *testing.T) {
+	items := []PopupItem{
+		{Label: "apple"},
+		{Label: "banana"},
+		{Label: "cherry"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+
+	// Type "an" → should filter to banana.
+	p.HandleKey("a", "a")
+	p.HandleKey("n", "n")
+
+	if !p.IsSearching() {
+		t.Error("expected IsSearching() to be true")
+	}
+	if len(p.filtered) == 0 {
+		t.Fatal("expected at least one filtered result")
+	}
+	// banana should match (contains "an").
+	found := false
+	for _, item := range p.filtered {
+		if item.Label == "banana" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Error("expected 'banana' in filtered results")
+	}
+
+	// Backspace removes last char.
+	p.HandleKey("backspace", "")
+	if p.search != "a" {
+		t.Errorf("expected search 'a' after backspace, got %q", p.search)
+	}
+
+	// Esc clears search.
+	res := p.HandleKey("esc", "")
+	if res.Cancelled {
+		t.Error("esc with search should clear search, not cancel")
+	}
+	if p.search != "" {
+		t.Errorf("expected empty search after esc, got %q", p.search)
+	}
+}
+
+func TestPopupList_HandleKey_SelectAndCancel(t *testing.T) {
+	items := []PopupItem{
+		{Label: "alpha", Meta: "first"},
+		{Label: "beta", Meta: "second"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+
+	// Select first item.
+	res := p.HandleKey("enter", "")
+	if res.Selected == nil {
+		t.Fatal("expected a selection on enter")
+	}
+	if res.Selected.Label != "alpha" {
+		t.Errorf("expected 'alpha', got %q", res.Selected.Label)
+	}
+	if res.Selected.Meta != "first" {
+		t.Errorf("expected meta 'first', got %v", res.Selected.Meta)
+	}
+
+	// Cancel with esc (no search text).
+	p2 := NewPopupList("Test", items, 80, 40)
+	res = p2.HandleKey("esc", "")
+	if !res.Cancelled {
+		t.Error("expected Cancelled on esc with no search")
+	}
+}
+
+func TestPopupList_DefaultFilter(t *testing.T) {
+	items := []PopupItem{
+		{Label: "foo-bar"},
+		{Label: "baz-qux"},
+		{Label: "foobar"},
+	}
+
+	// Exact prefix.
+	result := defaultFilter("foo", items)
+	if len(result) < 2 {
+		t.Fatalf("expected at least 2 matches for 'foo', got %d", len(result))
+	}
+	// "foobar" should rank higher (shorter match) or equal to "foo-bar".
+	if result[0].Label != "foobar" && result[1].Label != "foobar" {
+		t.Error("expected 'foobar' in top results")
+	}
+
+	// No match.
+	result = defaultFilter("zzz", items)
+	if len(result) != 0 {
+		t.Errorf("expected 0 matches for 'zzz', got %d", len(result))
+	}
+}
+
+func TestPopupList_CustomFilterFunc(t *testing.T) {
+	items := []PopupItem{
+		{Label: "alpha"},
+		{Label: "beta"},
+		{Label: "gamma"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+	p.FilterFunc = func(query string, allItems []PopupItem) []PopupItem {
+		// Custom: only return items whose label starts with query.
+		var result []PopupItem
+		for _, item := range allItems {
+			if strings.HasPrefix(item.Label, query) {
+				result = append(result, item)
+			}
+		}
+		return result
+	}
+
+	p.HandleKey("b", "b")
+	if len(p.filtered) != 1 || p.filtered[0].Label != "beta" {
+		t.Errorf("expected ['beta'], got %v", p.filtered)
+	}
+}
+
+func TestPopupList_Render(t *testing.T) {
+	items := []PopupItem{
+		{Label: "alpha", Description: "[test]"},
+		{Label: "beta", Description: "[test]", Active: true},
+	}
+	p := NewPopupList("My List", items, 80, 40)
+	p.Subtitle = "Some subtitle"
+
+	rendered := p.Render()
+	if rendered == "" {
+		t.Fatal("expected non-empty rendered output")
+	}
+
+	// Strip ANSI escape sequences for content checking.
+	plain := stripAnsi(rendered)
+	if !strings.Contains(plain, "My List") {
+		t.Error("expected title 'My List' in rendered output")
+	}
+	if !strings.Contains(plain, "alpha") {
+		t.Error("expected 'alpha' in rendered output")
+	}
+	if !strings.Contains(plain, "beta") {
+		t.Error("expected 'beta' in rendered output")
+	}
+	if !strings.Contains(plain, "✓") {
+		t.Error("expected checkmark for active item")
+	}
+}
+
+func TestPopupList_RenderCentered(t *testing.T) {
+	items := []PopupItem{
+		{Label: "item1"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+
+	centered := p.RenderCentered(80, 40)
+	if centered == "" {
+		t.Fatal("expected non-empty centered output")
+	}
+	// Should contain newlines for vertical centering.
+	lines := strings.Split(centered, "\n")
+	if len(lines) < 10 {
+		t.Errorf("expected centered output to have many lines, got %d", len(lines))
+	}
+}
+
+func TestPopupList_EmptyItems(t *testing.T) {
+	p := NewPopupList("Empty", nil, 80, 40)
+
+	rendered := p.Render()
+	if !strings.Contains(rendered, "No items") {
+		t.Error("expected 'No items' for empty list")
+	}
+
+	// Navigate on empty list shouldn't panic.
+	p.HandleKey("down", "")
+	p.HandleKey("up", "")
+	res := p.HandleKey("enter", "")
+	if res.Selected != nil {
+		t.Error("enter on empty list should not select")
+	}
+}
+
+func TestPopupList_SearchNoResults(t *testing.T) {
+	items := []PopupItem{
+		{Label: "alpha"},
+		{Label: "beta"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+
+	// Type something that doesn't match.
+	p.HandleKey("z", "z")
+	p.HandleKey("z", "z")
+	p.HandleKey("z", "z")
+
+	rendered := p.Render()
+	if !strings.Contains(rendered, "No matches") {
+		t.Error("expected 'No matches' message for empty search results")
+	}
+}
+
+func TestPopupList_CursorClamping(t *testing.T) {
+	items := []PopupItem{
+		{Label: "alpha"},
+		{Label: "beta"},
+		{Label: "gamma"},
+	}
+	p := NewPopupList("Test", items, 80, 40)
+
+	// Move to last item.
+	p.HandleKey("end", "")
+	if p.cursor != 2 {
+		t.Fatalf("expected cursor 2, got %d", p.cursor)
+	}
+
+	// Search that reduces list to 1 item → cursor should clamp.
+	p.HandleKey("a", "a")
+	p.HandleKey("l", "l")
+	// Only "alpha" should match.
+	if p.cursor >= len(p.filtered) {
+		t.Errorf("cursor %d should be < filtered count %d", p.cursor, len(p.filtered))
+	}
+}
+
+// stripAnsi is defined in usage_tracker_render_test.go

internal/ui/prefs/preferences.go

@@ -1,4 +1,4 @@
-package ui
+package prefs
 
 import (
 	"os"

internal/ui/progress/ollama.go

@@ -288,3 +288,9 @@ func (pr *ProgressReader) Close() error {
 
 	return nil
 }
+
+// NewProgressReadCloser is a convenience wrapper around NewProgressReader that
+// returns an io.ReadCloser, suitable for use as a ProgressReaderFunc callback.
+func NewProgressReadCloser(r io.Reader) io.ReadCloser {
+	return NewProgressReader(r)
+}

internal/ui/prompt.go

@@ -7,6 +7,8 @@ import (
 	"charm.land/bubbles/v2/textarea"
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // ---------------------------------------------------------------------------
@@ -76,7 +78,7 @@ func newInputPrompt(message, placeholder, defaultValue string, width, height int
 	ta.Placeholder = placeholder
 	ta.ShowLineNumbers = false
 	ta.Prompt = ""
-	ta.CharLimit = 1000
+	ta.CharLimit = 0
 	ta.SetWidth(width - 12) // account for border + padding
 	ta.SetHeight(1)
 	ta.Focus()
@@ -204,7 +206,7 @@ func (p *promptOverlay) updateInput(msg tea.KeyPressMsg) (*promptResult, tea.Cmd
 // AppModel layout. The prompt replaces the normal input area (below the
 // separator and above the status bar) rather than taking over the full screen.
 func (p *promptOverlay) Render() string {
-	theme := GetTheme()
+	theme := style.GetTheme()
 	var content string
 
 	switch p.mode {
@@ -224,7 +226,7 @@ func (p *promptOverlay) Render() string {
 	)
 }
 
-func (p *promptOverlay) viewSelect(theme Theme) string {
+func (p *promptOverlay) viewSelect(theme style.Theme) string {
 	var lines []string
 	lines = append(lines, lipgloss.NewStyle().Bold(true).Foreground(theme.Text).Render(p.message))
 	lines = append(lines, "")
@@ -247,7 +249,7 @@ func (p *promptOverlay) viewSelect(theme Theme) string {
 	return strings.Join(lines, "\n")
 }
 
-func (p *promptOverlay) viewConfirm(theme Theme) string {
+func (p *promptOverlay) viewConfirm(theme style.Theme) string {
 	var lines []string
 	lines = append(lines, lipgloss.NewStyle().Bold(true).Foreground(theme.Text).Render(p.message))
 	lines = append(lines, "")
@@ -272,7 +274,7 @@ func (p *promptOverlay) viewConfirm(theme Theme) string {
 	return strings.Join(lines, "\n")
 }
 
-func (p *promptOverlay) viewInput(theme Theme) string {
+func (p *promptOverlay) viewInput(theme style.Theme) string {
 	var lines []string
 	lines = append(lines, lipgloss.NewStyle().Bold(true).Foreground(theme.Text).Render(p.message))
 	lines = append(lines, "")

internal/ui/render/blocks.go

@@ -0,0 +1,155 @@
+// Package render provides pure rendering functions for message blocks.
+// These functions are stateless and can be used by both streaming and
+// historical message rendering paths, eliminating code duplication.
+package render
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"charm.land/lipgloss/v2"
+	"github.com/indaco/herald"
+
+	"github.com/mark3labs/kit/internal/ui/style"
+)
+
+// 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]+`)
+
+// UserBlock renders a user message with herald Tip styling.
+// The width parameter controls line wrapping so long messages don't overflow.
+// Any @file tokens in the content are highlighted with the theme accent color.
+func UserBlock(content string, width int, ty *herald.Typography, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		content = "(empty message)"
+	}
+
+	// Wrap content before passing to herald Alert so long lines break
+	// inside the alert box. Subtract 4 to account for the alert bar
+	// prefix ("│ ") and a small margin.
+	if width > 4 {
+		content = lipgloss.Wrap(content, width-4, "")
+	}
+
+	// Highlight @file tokens with accent color so file references are
+	// visually distinct from surrounding prompt text.
+	content = highlightFileTokens(content, theme)
+
+	rendered := ty.Tip(content)
+	return styleMarginBottom(theme, rendered)
+}
+
+// highlightFileTokens wraps @file tokens in the given text with the theme
+// accent color so they stand out visually in rendered user messages.
+func highlightFileTokens(text string, theme style.Theme) string {
+	accentStyle := lipgloss.NewStyle().Foreground(theme.Accent).Bold(true)
+	return fileTokenPattern.ReplaceAllStringFunc(text, func(token string) string {
+		return accentStyle.Render(token)
+	})
+}
+
+// AssistantBlock renders an assistant message with markdown styling.
+func AssistantBlock(content string, width int, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		return ""
+	}
+
+	rendered := style.ToMarkdown(content, width-4)
+	return styleMarginBottom(theme, rendered)
+}
+
+// ReasoningBlock renders a reasoning/thinking block with muted italic text.
+// If duration > 0, shows "Thought for Xs" label. Otherwise shows just "Thought".
+func ReasoningBlock(content string, duration int64, ty *herald.Typography, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		return ""
+	}
+
+	// Match live streaming styling: muted italic text
+	lines := strings.Split(strings.TrimRight(content, "\n"), "\n")
+	contentStr := strings.TrimLeft(strings.Join(lines, "\n"), " \t\n")
+	mutedStyle := lipgloss.NewStyle().Foreground(theme.Muted)
+	contentRendered := mutedStyle.Render(ty.Italic(contentStr))
+
+	// Build label based on duration
+	if duration > 0 {
+		var durationStr string
+		if duration < 1000 {
+			durationStr = fmt.Sprintf("%dms", duration)
+		} else {
+			durationStr = fmt.Sprintf("%.1fs", float64(duration)/1000)
+		}
+		labelPart := lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("Thought for ")
+		durationPart := lipgloss.NewStyle().Foreground(theme.Accent).Render(durationStr)
+		label := labelPart + durationPart
+		rendered := contentRendered + "\n" + label
+		return styleMarginBottom(theme, rendered)
+	}
+
+	label := lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("Thought")
+	rendered := contentRendered + "\n" + label
+
+	return styleMarginBottom(theme, rendered)
+}
+
+// SystemBlock renders a system message with herald Note styling.
+func SystemBlock(content string, ty *herald.Typography, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		content = "No content available"
+	}
+
+	rendered := ty.Note(content)
+	return styleMarginBottom(theme, rendered)
+}
+
+// ErrorBlock renders an error message with herald Caution styling.
+func ErrorBlock(errorMsg string, ty *herald.Typography, theme style.Theme) string {
+	rendered := ty.Caution(errorMsg)
+	return styleMarginBottom(theme, rendered)
+}
+
+// ToolBlock renders a tool execution result with header and body.
+func ToolBlock(displayName, params, body string, isError bool, width int, ty *herald.Typography, theme style.Theme) string {
+	var icon string
+	iconColor := theme.Success
+	if isError {
+		icon = "×"
+		iconColor = theme.Error
+	} else {
+		icon = "✓"
+	}
+
+	// Style the tool name with color
+	nameColor := theme.Info
+	if isError {
+		nameColor = theme.Error
+	}
+	styledName := lipgloss.NewStyle().Foreground(nameColor).Bold(true).Render(displayName)
+	styledIcon := lipgloss.NewStyle().Foreground(iconColor).Render(icon)
+
+	// Build the content: icon + name + params on first line, then body
+	headerLine := styledIcon + " " + styledName
+	if params != "" {
+		headerLine += " " + lipgloss.NewStyle().Foreground(theme.Muted).Render(params)
+	}
+
+	if strings.TrimSpace(body) == "" {
+		body = ty.Italic("(no output)")
+	}
+
+	// Compose: icon + name + params, then body
+	fullContent := ty.Compose(
+		headerLine,
+		"",
+		body,
+	)
+	return styleMarginBottom(theme, fullContent)
+}
+
+// styleMarginBottom applies a 1-line margin bottom using the theme.
+func styleMarginBottom(theme style.Theme, content string) string {
+	return lipgloss.NewStyle().MarginBottom(1).Render(content)
+}

internal/ui/render/blocks_test.go

@@ -0,0 +1,110 @@
+package render
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/indaco/herald"
+
+	"github.com/mark3labs/kit/internal/ui/style"
+)
+
+// testTypography creates a herald Typography for tests.
+func testTypography(theme style.Theme) *herald.Typography {
+	return herald.New(
+		herald.WithPalette(herald.ColorPalette{
+			Primary:   theme.Primary,
+			Secondary: theme.Secondary,
+			Tertiary:  theme.Info,
+			Accent:    theme.Accent,
+			Highlight: theme.Highlight,
+			Muted:     theme.Muted,
+			Text:      theme.Text,
+			Surface:   theme.Background,
+			Base:      theme.CodeBg,
+		}),
+		herald.WithAlertLabel(herald.AlertTip, "You"),
+	)
+}
+
+func TestHighlightFileTokens(t *testing.T) {
+	theme := style.DefaultTheme()
+
+	tests := []struct {
+		name     string
+		input    string
+		wantHas  []string // substrings that must be present in the output
+		wantNone []string // substrings that must NOT be present as plain text
+	}{
+		{
+			name:    "no tokens",
+			input:   "hello world",
+			wantHas: []string{"hello world"},
+		},
+		{
+			name:    "single unquoted token",
+			input:   "refactor @main.go please",
+			wantHas: []string{"@main.go", "refactor", "please"},
+		},
+		{
+			name:    "quoted token with spaces",
+			input:   `check @"path with spaces/file.txt" out`,
+			wantHas: []string{`@"path with spaces/file.txt"`, "check", "out"},
+		},
+		{
+			name:    "multiple tokens",
+			input:   "@main.go @utils.go refactor these",
+			wantHas: []string{"@main.go", "@utils.go", "refactor these"},
+		},
+		{
+			name:    "path with directory",
+			input:   "look at @internal/ui/render/blocks.go",
+			wantHas: []string{"@internal/ui/render/blocks.go", "look at"},
+		},
+		{
+			name:    "empty string",
+			input:   "",
+			wantHas: []string{""},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := highlightFileTokens(tt.input, theme)
+
+			for _, want := range tt.wantHas {
+				if !strings.Contains(result, want) {
+					t.Errorf("highlightFileTokens(%q) = %q, want substring %q", tt.input, result, want)
+				}
+			}
+
+			// If there were @tokens, the result should contain ANSI escape
+			// sequences (from lipgloss styling).
+			if fileTokenPattern.MatchString(tt.input) && !strings.Contains(result, "\x1b[") {
+				t.Errorf("highlightFileTokens(%q) should contain ANSI escapes for @tokens but got %q", tt.input, result)
+			}
+		})
+	}
+}
+
+func TestUserBlockHighlightsFileTokens(t *testing.T) {
+	theme := style.DefaultTheme()
+	ty := testTypography(theme)
+
+	// A user message with @file tokens should contain ANSI escapes around the token.
+	content := "refactor @main.go and @utils.go"
+	result := UserBlock(content, 80, ty, theme)
+
+	// The rendered output should contain both file references.
+	if !strings.Contains(result, "@main.go") {
+		t.Errorf("UserBlock output should contain @main.go, got:\n%s", result)
+	}
+	if !strings.Contains(result, "@utils.go") {
+		t.Errorf("UserBlock output should contain @utils.go, got:\n%s", result)
+	}
+
+	// Verify ANSI codes are present (the tokens are styled).
+	if !strings.Contains(result, "\x1b[") {
+		t.Errorf("UserBlock output should contain ANSI escape codes for styled @file tokens")
+	}
+}

internal/ui/scrolllist.go

@@ -2,25 +2,13 @@ package ui
 
 import (
 	"strings"
+	"time"
 
-	"charm.land/lipgloss/v2"
+	xansi "github.com/charmbracelet/x/ansi"
+
+	"github.com/mark3labs/kit/internal/ui/selection"
 )
 
-// highlightStyle is lazily initialized to avoid creating it on every render
-var highlightStyle lipgloss.Style
-
-// initHighlightStyle creates the highlight style with proper colors
-func initHighlightStyle() lipgloss.Style {
-	if highlightStyle.String() == "" {
-		theme := GetTheme()
-		highlightStyle = lipgloss.NewStyle().
-			Background(theme.Secondary).
-			Foreground(theme.Background).
-			Bold(true)
-	}
-	return highlightStyle
-}
-
 // MessageItem is the interface all scrollback messages must implement.
 // This allows lazy rendering - messages are only rendered when visible.
 type MessageItem interface {
@@ -36,8 +24,8 @@ type MessageItem interface {
 }
 
 // ScrollList manages a viewport over a list of MessageItems.
-// It handles offset-based scrolling and lazy rendering. Only visible
-// items are rendered on each View() call.
+// It handles offset-based scrolling, lazy rendering, and character-level
+// text selection (crush-style). Only visible items are rendered on each View() call.
 type ScrollList struct {
 	items      []MessageItem
 	offsetIdx  int // Index of first visible item
@@ -46,15 +34,9 @@ type ScrollList struct {
 	height     int  // Viewport height in lines
 	autoScroll bool // Whether to auto-scroll to bottom on new content
 	itemGap    int  // Number of blank lines between items (0 = no gap)
-	focusedIdx int  // Index of focused/selected item (-1 = none)
-	selectable bool // Whether items can be selected via mouse/keyboard
 
-	// Selection tracking for copy+paste (crush-style)
-	selection     CopySelection // Current text selection
-	mouseDown     bool          // Whether mouse button is currently down
-	mouseDownX    int           // X coordinate where mouse was pressed
-	mouseDownY    int           // Y coordinate where mouse was pressed
-	mouseDownItem int           // Item index where mouse was pressed
+	// Character-level text selection (crush-style).
+	sel selection.State
 }
 
 // NewScrollList creates a new ScrollList with the given dimensions.
@@ -65,7 +47,8 @@ func NewScrollList(width, height int) *ScrollList {
 		offsetLine: 0,
 		width:      width,
 		height:     height,
-		autoScroll: true, // Start with auto-scroll enabled
+		autoScroll: true,
+		sel:        selection.NewState(),
 	}
 }
 
@@ -101,118 +84,210 @@ func (s *ScrollList) ItemGap() int {
 	return s.itemGap
 }
 
-// SetSelectable enables or disables item selection.
-func (s *ScrollList) SetSelectable(selectable bool) {
-	s.selectable = selectable
-}
+// --------------------------------------------------------------------------
+// Mouse event handling — character-level text selection (crush-style)
+// --------------------------------------------------------------------------
 
-// FocusedIdx returns the currently focused item index (-1 if none).
-func (s *ScrollList) FocusedIdx() int {
-	return s.focusedIdx
-}
-
-// SetFocused sets the focused item by index.
-func (s *ScrollList) SetFocused(idx int) {
-	if idx < -1 {
-		s.focusedIdx = -1
-	} else if idx >= len(s.items) {
-		s.focusedIdx = len(s.items) - 1
-	} else {
-		s.focusedIdx = idx
-	}
-}
-
-// SelectItemAtY selects the item at the given Y coordinate (relative to viewport).
-// Returns the selected item index or -1 if no item at that position.
-func (s *ScrollList) SelectItemAtY(y int) int {
-	if !s.selectable || len(s.items) == 0 || y < 0 || y >= s.height {
-		return -1
-	}
-
-	// Calculate which item is at the given Y position
-	currentY := 0
-	for idx := s.offsetIdx; idx < len(s.items); idx++ {
-		item := s.items[idx]
-		itemHeight := item.Height()
-
-		// Check if y falls within this item
-		if y >= currentY && y < currentY+itemHeight {
-			s.focusedIdx = idx
-			return idx
-		}
-
-		currentY += itemHeight
-
-		// Add gap after item (except last)
-		if s.itemGap > 0 && idx < len(s.items)-1 {
-			currentY += s.itemGap
-		}
-
-		// Stop if we've passed the viewport
-		if currentY >= s.height {
-			break
-		}
-	}
-
-	return -1
-}
-
-// HandleMouseDown handles mouse button press for selection (crush-style).
+// HandleMouseDown handles mouse button press. Detects single, double, and
+// triple clicks for character, word, and line selection respectively.
 // Returns true if the click was handled.
 func (s *ScrollList) HandleMouseDown(x, y int) bool {
-	if !s.selectable || len(s.items) == 0 {
+	if len(s.items) == 0 {
 		return false
 	}
 
-	s.mouseDown = true
-	s.mouseDownX = x
-	s.mouseDownY = y
-
-	// Find which item and line was clicked
-	itemIdx, lineIdx := s.getItemAndLineAtY(y)
-	s.mouseDownItem = itemIdx
-
-	// Start a new selection at click position
-	if itemIdx >= 0 {
-		s.selection = CopySelection{
-			StartItemIdx: itemIdx,
-			StartLine:    lineIdx,
-			StartCol:     x,
-			EndItemIdx:   itemIdx,
-			EndLine:      lineIdx,
-			EndCol:       x,
-			Active:       true,
-		}
-		return true
-	}
-
-	return false
-}
-
-// HandleMouseDrag handles mouse drag for selection (crush-style).
-// Updates the selection end point. Returns true if selection changed.
-func (s *ScrollList) HandleMouseDrag(x, y int) bool {
-	if !s.mouseDown || !s.selectable {
-		return false
-	}
-
-	// Find which item and line we're dragging over
 	itemIdx, lineIdx := s.getItemAndLineAtY(y)
 	if itemIdx < 0 {
 		return false
 	}
 
-	// Update selection end point
-	s.selection.EndItemIdx = itemIdx
-	s.selection.EndLine = lineIdx
-	s.selection.EndCol = x
-	s.selection.Active = true
+	// Multi-click detection (crush-style).
+	now := time.Now()
+	if now.Sub(s.sel.LastClickTime) <= selection.DoubleClickThreshold &&
+		abs(x-s.sel.LastClickX) <= selection.ClickTolerance &&
+		abs(y-s.sel.LastClickY) <= selection.ClickTolerance {
+		s.sel.ClickCount++
+	} else {
+		s.sel.ClickCount = 1
+	}
+	s.sel.LastClickTime = now
+	s.sel.LastClickX = x
+	s.sel.LastClickY = y
+
+	switch s.sel.ClickCount {
+	case 1:
+		// Single click: start character-level drag selection.
+		s.sel.MouseDown = true
+		s.sel.MouseDownItemIdx = itemIdx
+		s.sel.MouseDownLineIdx = lineIdx
+		s.sel.MouseDownCol = x
+		s.sel.DragItemIdx = itemIdx
+		s.sel.DragLineIdx = lineIdx
+		s.sel.DragCol = x
+
+	case 2:
+		// Double click: select word at position.
+		s.selectWord(itemIdx, lineIdx, x)
+
+	case 3:
+		// Triple click: select entire line.
+		s.selectLine(itemIdx, lineIdx)
+		s.sel.ClickCount = 0 // Reset after triple
+	}
 
 	return true
 }
 
-// getItemAndLineAtY converts a Y coordinate to item index and line index within that item.
+// HandleMouseDrag handles mouse motion while button is held.
+// Updates the selection endpoint for character-level precision.
+// Returns true if selection was updated.
+func (s *ScrollList) HandleMouseDrag(x, y int) bool {
+	if !s.sel.MouseDown {
+		return false
+	}
+
+	if len(s.items) == 0 {
+		return false
+	}
+
+	itemIdx, lineIdx := s.getItemAndLineAtY(y)
+	if itemIdx < 0 {
+		return false
+	}
+
+	s.sel.DragItemIdx = itemIdx
+	s.sel.DragLineIdx = lineIdx
+	s.sel.DragCol = x
+
+	return true
+}
+
+// HandleMouseUp handles mouse button release.
+// Returns true if there was an active selection.
+func (s *ScrollList) HandleMouseUp() bool {
+	if !s.sel.MouseDown {
+		return false
+	}
+	s.sel.MouseDown = false
+	return s.sel.HasSelection()
+}
+
+// HasSelection returns true if there is a non-empty active selection.
+func (s *ScrollList) HasSelection() bool {
+	return s.sel.HasSelection()
+}
+
+// ClearSelection clears the current text selection.
+func (s *ScrollList) ClearSelection() {
+	s.sel.Clear()
+}
+
+// ExtractSelectedText returns the plain text content of the current selection
+// by walking through selected items and extracting text at the character level
+// using the ultraviolet cell buffer (ANSI-aware).
+func (s *ScrollList) ExtractSelectedText() string {
+	r := s.sel.GetRange()
+	if r.IsEmpty() {
+		return ""
+	}
+
+	var sb strings.Builder
+
+	for itemIdx := r.StartItemIdx; itemIdx <= r.EndItemIdx && itemIdx < len(s.items); itemIdx++ {
+		item := s.items[itemIdx]
+		content := item.Render(s.width)
+		contentLines := strings.Split(content, "\n")
+
+		for lineIdx, line := range contentLines {
+			inRange, startCol, endCol := selection.IsLineInRange(r, itemIdx, lineIdx)
+			if !inRange {
+				continue
+			}
+
+			text := selection.ExtractText(line, startCol, endCol)
+			if text != "" {
+				if sb.Len() > 0 {
+					sb.WriteString("\n")
+				}
+				sb.WriteString(text)
+			}
+		}
+	}
+
+	return sb.String()
+}
+
+// selectWord selects the word at the given position using UAX#29 word
+// segmentation and display-width-aware column calculations.
+func (s *ScrollList) selectWord(itemIdx, lineIdx, x int) {
+	if itemIdx < 0 || itemIdx >= len(s.items) {
+		return
+	}
+
+	item := s.items[itemIdx]
+	content := item.Render(s.width)
+	lines := strings.Split(content, "\n")
+	if lineIdx < 0 || lineIdx >= len(lines) {
+		return
+	}
+
+	// Strip ANSI codes for word boundary detection.
+	plainLine := xansi.Strip(lines[lineIdx])
+	startCol, endCol := selection.FindWordBoundaries(plainLine, x)
+
+	if startCol == endCol {
+		// No word at this position — set up single-click drag state.
+		s.sel.MouseDown = true
+		s.sel.MouseDownItemIdx = itemIdx
+		s.sel.MouseDownLineIdx = lineIdx
+		s.sel.MouseDownCol = x
+		s.sel.DragItemIdx = itemIdx
+		s.sel.DragLineIdx = lineIdx
+		s.sel.DragCol = x
+		return
+	}
+
+	// Set selection to the word boundaries.
+	s.sel.MouseDown = true
+	s.sel.MouseDownItemIdx = itemIdx
+	s.sel.MouseDownLineIdx = lineIdx
+	s.sel.MouseDownCol = startCol
+	s.sel.DragItemIdx = itemIdx
+	s.sel.DragLineIdx = lineIdx
+	s.sel.DragCol = endCol
+}
+
+// selectLine selects the entire line at the given position.
+func (s *ScrollList) selectLine(itemIdx, lineIdx int) {
+	if itemIdx < 0 || itemIdx >= len(s.items) {
+		return
+	}
+
+	item := s.items[itemIdx]
+	content := item.Render(s.width)
+	lines := strings.Split(content, "\n")
+	if lineIdx < 0 || lineIdx >= len(lines) {
+		return
+	}
+
+	lineWidth := xansi.StringWidth(lines[lineIdx])
+
+	s.sel.MouseDown = true
+	s.sel.MouseDownItemIdx = itemIdx
+	s.sel.MouseDownLineIdx = lineIdx
+	s.sel.MouseDownCol = 0
+	s.sel.DragItemIdx = itemIdx
+	s.sel.DragLineIdx = lineIdx
+	s.sel.DragCol = lineWidth
+}
+
+// getItemAndLineAtY converts a viewport-relative Y coordinate to item index
+// and line index within that item. Accounts for scroll offset and item gaps.
 // Returns (-1, -1) if Y is outside the viewport or beyond all items.
+//
+// IMPORTANT: Uses Render()+line counting (not Height()) to compute item height,
+// because Height() on some MessageItem implementations (e.g. StreamingMessageItem
+// for reasoning blocks) may return 0 when the render cache is empty.
 func (s *ScrollList) getItemAndLineAtY(y int) (itemIdx, lineIdx int) {
 	if y < 0 || y >= s.height || len(s.items) == 0 {
 		return -1, -1
@@ -221,21 +296,27 @@ func (s *ScrollList) getItemAndLineAtY(y int) (itemIdx, lineIdx int) {
 	currentY := 0
 	for idx := s.offsetIdx; idx < len(s.items); idx++ {
 		item := s.items[idx]
-		itemHeight := item.Height()
+		// Compute height the same way View() does: render, then count lines.
+		itemHeight := s.renderedHeight(item)
+
+		// Account for partial visibility of the first item.
+		startLine := 0
+		if idx == s.offsetIdx {
+			startLine = s.offsetLine
+			itemHeight -= s.offsetLine
+		}
 
-		// Check if y falls within this item
 		if y >= currentY && y < currentY+itemHeight {
-			return idx, y - currentY
+			return idx, (y - currentY) + startLine
 		}
 
 		currentY += itemHeight
 
-		// Add gap after item (except last)
+		// Add gap after item (except last).
 		if s.itemGap > 0 && idx < len(s.items)-1 {
 			currentY += s.itemGap
 		}
 
-		// Stop if we've passed the viewport
 		if currentY >= s.height {
 			break
 		}
@@ -244,38 +325,9 @@ func (s *ScrollList) getItemAndLineAtY(y int) (itemIdx, lineIdx int) {
 	return -1, -1
 }
 
-// HandleMouseUp handles mouse button release (crush-style).
-// Finalizes selection and returns true if there was an active selection.
-func (s *ScrollList) HandleMouseUp(x, y int) bool {
-	if !s.mouseDown {
-		return false
-	}
-
-	s.mouseDown = false
-
-	// Check if we have a valid selection
-	if s.selection.Active && !s.selection.IsEmpty() {
-		return true
-	}
-
-	return false
-}
-
-// GetSelection returns the current text selection.
-func (s *ScrollList) GetSelection() CopySelection {
-	return s.selection
-}
-
-// ClearSelection clears the current text selection.
-func (s *ScrollList) ClearSelection() {
-	s.selection = CopySelection{}
-	s.mouseDown = false
-}
-
-// HasSelection returns true if there is an active non-empty selection.
-func (s *ScrollList) HasSelection() bool {
-	return s.selection.Active && !s.selection.IsEmpty()
-}
+// --------------------------------------------------------------------------
+// Scrolling
+// --------------------------------------------------------------------------
 
 // ScrollBy scrolls the viewport by the given number of lines.
 // Positive = scroll down, negative = scroll up.
@@ -361,14 +413,11 @@ func (s *ScrollList) GotoBottom() {
 	}
 
 	// Calculate total height including gaps
-	// Ensure items are rendered before checking height (iteratr pattern)
 	totalHeight := 0
 	for i, item := range s.items {
-		// Render to get actual content (handles non-cached items like reasoning blocks)
 		rendered := item.Render(s.width)
 		itemHeight := strings.Count(rendered, "\n") + 1
 		totalHeight += itemHeight
-		// Add gap after each item except the last
 		if s.itemGap > 0 && i < len(s.items)-1 {
 			totalHeight += s.itemGap
 		}
@@ -384,7 +433,6 @@ func (s *ScrollList) GotoBottom() {
 	// Otherwise, position viewport at bottom
 	remaining := totalHeight - s.height
 	for idx := 0; idx < len(s.items); idx++ {
-		// Render to get actual content
 		rendered := s.items[idx].Render(s.width)
 		itemHeight := strings.Count(rendered, "\n") + 1
 		if remaining < itemHeight {
@@ -393,7 +441,6 @@ func (s *ScrollList) GotoBottom() {
 			return
 		}
 		remaining -= itemHeight
-		// Subtract gap after item (except last)
 		if s.itemGap > 0 && idx < len(s.items)-1 {
 			remaining -= s.itemGap
 		}
@@ -416,12 +463,9 @@ func (s *ScrollList) AtBottom() bool {
 		return true
 	}
 
-	// Calculate visible height from current position including gaps
-	// Calculate height directly from rendered content (handles non-cached items)
 	visibleHeight := 0
 	for idx := s.offsetIdx; idx < len(s.items); idx++ {
 		item := s.items[idx]
-		// Render to get actual content
 		rendered := item.Render(s.width)
 		itemHeight := strings.Count(rendered, "\n") + 1
 
@@ -431,7 +475,6 @@ func (s *ScrollList) AtBottom() bool {
 			visibleHeight += itemHeight
 		}
 
-		// Add gap after item (except last)
 		if s.itemGap > 0 && idx < len(s.items)-1 {
 			visibleHeight += s.itemGap
 		}
@@ -449,19 +492,28 @@ func (s *ScrollList) AtTop() bool {
 	return s.offsetIdx == 0 && s.offsetLine == 0
 }
 
+// --------------------------------------------------------------------------
+// Rendering
+// --------------------------------------------------------------------------
+
 // View renders the visible portion of the scrollback.
 // Only items that fit within the viewport height are rendered.
 // ALWAYS returns exactly s.height lines (padded with empty lines if needed)
 // to ensure the input/footer stay fixed at the bottom.
+//
+// When an active selection exists, character-level highlighting is applied
+// using ultraviolet ScreenBuffer for ANSI-aware cell manipulation.
 func (s *ScrollList) View() string {
 	if s.height <= 0 {
 		return ""
 	}
 
+	selRange := s.sel.GetRange()
+	hasSelection := !selRange.IsEmpty()
+
 	var lines []string
 	remainingHeight := s.height
 
-	// Render visible items
 	if len(s.items) > 0 {
 		for idx := s.offsetIdx; idx < len(s.items) && remainingHeight > 0; idx++ {
 			item := s.items[idx]
@@ -473,25 +525,22 @@ func (s *ScrollList) View() string {
 				startLine = s.offsetLine
 			}
 
-			// Check if this item is focused (for visual indicator)
-			isFocused := idx == s.focusedIdx
-
 			for i := startLine; i < len(contentLines) && remainingHeight > 0; i++ {
 				line := contentLines[i]
 
-				// Apply selection highlighting if this line is within selection
-				if s.selection.Active && s.isLineInSelection(idx, i) {
-					line = s.applyHighlight(line)
-				} else if isFocused && s.selectable {
-					// Apply subtle focus indicator when item is focused but not in selection
-					line = s.applyFocusIndicator(line)
+				// Apply character-level selection highlighting.
+				if hasSelection {
+					inRange, startCol, endCol := selection.IsLineInRange(selRange, idx, i)
+					if inRange {
+						line = selection.HighlightLine(line, startCol, endCol)
+					}
 				}
 
 				lines = append(lines, line)
 				remainingHeight--
 			}
 
-			// Add gap lines between items (but not after the last visible item)
+			// Add gap lines between items.
 			if remainingHeight > 0 && idx < len(s.items)-1 && s.itemGap > 0 {
 				for g := 0; g < s.itemGap && remainingHeight > 0; g++ {
 					lines = append(lines, "")
@@ -501,8 +550,7 @@ func (s *ScrollList) View() string {
 		}
 	}
 
-	// Pad with empty lines to ensure exactly s.height lines
-	// This keeps the input/footer fixed at the bottom of the screen
+	// Pad with empty lines to ensure exactly s.height lines.
 	for remainingHeight > 0 {
 		lines = append(lines, "")
 		remainingHeight--
@@ -511,65 +559,6 @@ func (s *ScrollList) View() string {
 	return strings.Join(lines, "\n")
 }
 
-// isLineInSelection checks if a specific line within an item is part of the current selection.
-func (s *ScrollList) isLineInSelection(itemIdx, lineIdx int) bool {
-	if !s.selection.Active {
-		return false
-	}
-
-	// Normalize selection (start <= end)
-	startItem := s.selection.StartItemIdx
-	startLine := s.selection.StartLine
-	endItem := s.selection.EndItemIdx
-	endLine := s.selection.EndLine
-
-	if startItem > endItem || (startItem == endItem && startLine > endLine) {
-		startItem, endItem = endItem, startItem
-		startLine, endLine = endLine, startLine
-	}
-
-	// Check if item is within selection range
-	if itemIdx < startItem || itemIdx > endItem {
-		return false
-	}
-
-	// For single item selection
-	if startItem == endItem {
-		return itemIdx == startItem && lineIdx >= startLine && lineIdx <= endLine
-	}
-
-	// For multi-item selection
-	if itemIdx == startItem {
-		return lineIdx >= startLine
-	}
-	if itemIdx == endItem {
-		return lineIdx <= endLine
-	}
-	// Middle items are fully selected
-	return itemIdx > startItem && itemIdx < endItem
-}
-
-// applyHighlight applies the highlight style to a line.
-// Uses the theme's Highlight color for the background.
-func (s *ScrollList) applyHighlight(line string) string {
-	if line == "" {
-		return line
-	}
-	// Apply background/foreground color change for selection
-	style := initHighlightStyle()
-	return style.Render(line)
-}
-
-// applyFocusIndicator applies a subtle visual indicator for focused items.
-func (s *ScrollList) applyFocusIndicator(line string) string {
-	if line == "" {
-		return line
-	}
-	// Just return the line as-is - no visual indicator for focus
-	// The selection highlighting is enough
-	return line
-}
-
 // ScrollPercent returns the current scroll position as a percentage (0.0-1.0).
 // 0.0 = at top, 1.0 = at bottom. Useful for scroll indicators.
 func (s *ScrollList) ScrollPercent() float64 {
@@ -583,10 +572,9 @@ func (s *ScrollList) ScrollPercent() float64 {
 	}
 
 	if totalHeight <= s.height {
-		return 1.0 // All content fits, consider it "at bottom"
+		return 1.0
 	}
 
-	// Calculate how many lines are above the viewport
 	linesAbove := 0
 	for i := 0; i < s.offsetIdx && i < len(s.items); i++ {
 		linesAbove += s.items[i].Height()
@@ -609,8 +597,7 @@ func (s *ScrollList) ScrollPercent() float64 {
 }
 
 // clampOffset ensures the offset values are within valid bounds after
-// resizing or scrolling operations. Prevents scrolling past the bottom
-// of content (showing empty space when there's content above).
+// resizing or scrolling operations.
 func (s *ScrollList) clampOffset() {
 	if len(s.items) == 0 {
 		s.offsetIdx = 0
@@ -618,7 +605,6 @@ func (s *ScrollList) clampOffset() {
 		return
 	}
 
-	// First, clamp offsetIdx to valid item range
 	if s.offsetIdx >= len(s.items) {
 		s.offsetIdx = len(s.items) - 1
 	}
@@ -626,9 +612,7 @@ func (s *ScrollList) clampOffset() {
 		s.offsetIdx = 0
 	}
 
-	// Clamp offsetLine within current item
 	if s.offsetIdx < len(s.items) {
-		// Calculate height from rendered content (handles non-cached items)
 		rendered := s.items[s.offsetIdx].Render(s.width)
 		itemHeight := strings.Count(rendered, "\n") + 1
 		if s.offsetLine >= itemHeight {
@@ -639,8 +623,7 @@ func (s *ScrollList) clampOffset() {
 		s.offsetLine = 0
 	}
 
-	// Prevent scrolling past the bottom (showing empty space at bottom when there's content above)
-	// Calculate total content height
+	// Prevent scrolling past the bottom
 	totalHeight := 0
 	for i, item := range s.items {
 		rendered := item.Render(s.width)
@@ -650,14 +633,12 @@ func (s *ScrollList) clampOffset() {
 		}
 	}
 
-	// If content fits in viewport, force start at top
 	if totalHeight <= s.height {
 		s.offsetIdx = 0
 		s.offsetLine = 0
 		return
 	}
 
-	// Calculate how many lines are currently above the viewport
 	linesAbove := 0
 	for i := 0; i < s.offsetIdx; i++ {
 		rendered := s.items[i].Render(s.width)
@@ -668,13 +649,8 @@ func (s *ScrollList) clampOffset() {
 	}
 	linesAbove += s.offsetLine
 
-	// Calculate how many lines are visible from current position to end
 	linesFromCurrentToEnd := totalHeight - linesAbove
-
-	// If there's less content remaining than the viewport height,
-	// we've scrolled past the bottom - need to back up
 	if linesFromCurrentToEnd < s.height {
-		// Position viewport so the last line of content is at the bottom
 		targetLine := totalHeight - s.height
 		currentLine := 0
 
@@ -683,7 +659,6 @@ func (s *ScrollList) clampOffset() {
 			itemHeight := strings.Count(rendered, "\n") + 1
 
 			if currentLine+itemHeight > targetLine {
-				// This item contains the target line
 				s.offsetIdx = idx
 				s.offsetLine = targetLine - currentLine
 				return
@@ -696,3 +671,23 @@ func (s *ScrollList) clampOffset() {
 		}
 	}
 }
+
+// renderedHeight returns the height of a message item in lines by actually
+// rendering it. This is the single source of truth for item height — it
+// matches exactly what View() produces, unlike item.Height() which may
+// return stale/zero values for uncached items (e.g. reasoning blocks).
+func (s *ScrollList) renderedHeight(item MessageItem) int {
+	rendered := item.Render(s.width)
+	if rendered == "" {
+		return 0
+	}
+	return strings.Count(rendered, "\n") + 1
+}
+
+// abs returns the absolute value of x.
+func abs(x int) int {
+	if x < 0 {
+		return -x
+	}
+	return x
+}