fix(mcp): propagate OAuth config for runtime-added servers

- Store authHandler and tokenStoreFactory on Agent struct so
  AddMCPServer() can propagate them to new MCPToolManagers (#3)
- Add OAuthClientID, OAuthClientSecret, OAuthScopes fields to
  MCPServerConfig for servers without dynamic registration (#4)
- Pass OAuth fields from server config to transport OAuthConfig
  in both SSE and Streamable HTTP client creation paths
- Add GetAuthHandler() accessor to MCPToolManager
- Add tests for auth handler propagation and OAuth config parsing

Closes #3, closes #4

.agents/skills/btca-cli/SKILL.md

@@ -1,64 +0,0 @@
----
-name: btca-cli
-description: Operate the btca CLI for local resources and source-first answers. Use when setting up btca in a project, connecting a provider, adding or managing resources, and asking questions via btca commands. Invoke this skill when the user says "use btca" or needs to do more detailed research on a specific library or framework.
----
-
-# btca CLI
-
-`btca` is a source-first research CLI. It hydrates resources (git, local, npm) into searchable context, then answers questions grounded in those sources. Use configured resources for ongoing work, or one-off anonymous resources directly in `btca ask`.
-
-Full CLI reference: https://docs.btca.dev/guides/cli-reference
-
-Add resources:
-
-```bash
-# Git resource
-btca add -n svelte-dev https://github.com/sveltejs/svelte.dev
-
-# Local directory
-btca add -n my-docs -t local /absolute/path/to/docs
-
-# npm package
-btca add npm:@types/node@22.10.1 -n node-types -t npm
-```
-
-Verify resources:
-
-```bash
-btca resources
-```
-
-Ask a question:
-
-```bash
-btca ask -r svelte-dev -q "How do I define remote functions?"
-```
-
-## Common Tasks
-
-- Ask with multiple resources:
-
-```bash
-btca ask -r react -r typescript -q "How do I type useState?"
-```
-
-- Ask with anonymous one-off resources (not saved to config):
-
-```bash
-# One-off git repo
-btca ask -r https://github.com/sveltejs/svelte -q "Where is the implementation of writable stores?"
-
-# One-off npm package
-btca ask -r npm:react@19.0.0 -q "How is useTransition exported?"
-```
-
-## Config Overview
-
-- Config lives in `btca.config.jsonc` (project) and `~/.config/btca/btca.config.jsonc` (global).
-- Project config overrides global and controls provider/model and resources.
-
-## Troubleshooting
-
-- "No resources configured": add resources with `btca add ...` and re-run `btca resources`.
-- "Provider not connected": run `btca connect` and follow the prompts.
-- "Unknown resource": use `btca resources` for configured names, or pass a valid HTTPS git URL / `npm:<package>` as an anonymous one-off in `btca ask`.

.agents/skills/btca-cli/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "BTCA CLI"
-  short_description: "Help with BTCA CLI setup and usage workflows"

.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

.github/workflows/pages.yml

@@ -0,0 +1,32 @@
+name: Build and Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        working-directory: ./www
+        run: bun install
+
+      - name: Build
+        working-directory: ./www
+        run: bun run build
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: www/out
+          branch: gh-pages

.github/workflows/release.yml

@@ -39,12 +39,42 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  npm-publish:
+    runs-on: ubuntu-latest
+    needs: goreleaser
+    if: ${{ always() && (needs.goreleaser.result == 'success' || needs.goreleaser.result == 'skipped') }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Set version from tag
+        working-directory: npm
+        run: |
+          TAG=${{ inputs.tag || github.ref_name }}
+          VERSION=${TAG#v}
+          echo "Setting npm version to $VERSION"
+          npm version $VERSION --no-git-tag-version
+
+      - name: Publish to npm
+        working-directory: npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  notify:
+    runs-on: ubuntu-latest
+    needs: [goreleaser, npm-publish]
+    if: ${{ always() && (needs.goreleaser.result == 'success' || needs.goreleaser.result == 'skipped') && (needs.npm-publish.result == 'success') }}
+    steps:
       - name: Send Discord Notification
-        if: success()
         env:
           DISCORD_WEBHOOK: ${{ secrets.RELEASES_WEBHOOK }}
-          TAG_NAME: ${{ github.ref_name }}
-          RELEASE_URL: https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}
+          TAG_NAME: ${{ inputs.tag || github.ref_name }}
+          RELEASE_URL: https://github.com/${{ github.repository }}/releases/tag/${{ inputs.tag || github.ref_name }}
         run: |
           curl -H "Content-Type: application/json" \
             -X POST \
@@ -73,29 +103,3 @@ jobs:
               }]
             }" \
             $DISCORD_WEBHOOK
-
-  npm-publish:
-    runs-on: ubuntu-latest
-    needs: goreleaser
-    if: ${{ always() && (needs.goreleaser.result == 'success' || needs.goreleaser.result == 'skipped') }}
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "24"
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Set version from tag
-        working-directory: npm
-        run: |
-          TAG=${{ inputs.tag || github.ref_name }}
-          VERSION=${TAG#v}
-          echo "Setting npm version to $VERSION"
-          npm version $VERSION --no-git-tag-version
-
-      - name: Publish to npm
-        working-directory: npm
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,14 +1,17 @@
 .aider*
 .task/
 .env
-.kit/
+.kit/*
+!.kit/extensions/
+!.kit/prompts/
 aidocs/
 *.log
 /kit
 .idea
-test/
 build/
 dist/
 contribute/output/
 CONTEXT.md
 output/
+.agents/
+skills-lock.json

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

@@ -0,0 +1,268 @@
+//go:build ignore
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"kit/ext"
+)
+
+const (
+	diagnosticsTimeout = 20 * time.Second
+	maxOutputBytes     = 12_000
+)
+
+type toolPathInput struct {
+	Path string `json:"path"`
+}
+
+type lintResult struct {
+	Output string
+	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 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
+		}
+
+		absPath, ok := resolveGoFilePath(e.Input, ctx.CWD)
+		if !ok {
+			return nil
+		}
+
+		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
+		}
+
+		// 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("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))
+			}
+
+			borderColor := "#f9e2af" // yellow
+			if goplsIssues > 0 && lintIssues > 0 {
+				borderColor = "#f38ba8" // red
+			}
+
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        strings.Join(msgLines, "\n"),
+				BorderColor: borderColor,
+				Subtitle:    "go-edit-lint",
+			})
+
+			// 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",
+			})
+		}
+	})
+}
+
+func isEditOrWrite(toolName string) bool {
+	return strings.EqualFold(toolName, "edit") || strings.EqualFold(toolName, "write")
+}
+
+func resolveGoFilePath(inputJSON, cwd string) (string, bool) {
+	var args toolPathInput
+	if err := json.Unmarshal([]byte(inputJSON), &args); err != nil || args.Path == "" {
+		return "", false
+	}
+
+	absPath := args.Path
+	if !filepath.IsAbs(absPath) {
+		absPath = filepath.Join(cwd, absPath)
+	}
+
+	if strings.ToLower(filepath.Ext(absPath)) != ".go" {
+		return "", false
+	}
+
+	return absPath, true
+}
+
+func runGopls(cwd, absPath string) lintResult {
+	ctx, cancel := context.WithTimeout(context.Background(), diagnosticsTimeout)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "gopls", "check", absPath)
+	cmd.Dir = cwd
+	out, err := cmd.CombinedOutput()
+
+	if ctx.Err() == context.DeadlineExceeded {
+		return lintResult{Err: fmt.Errorf("timed out after %s", diagnosticsTimeout)}
+	}
+
+	if err != nil {
+		return lintResult{Output: truncate(string(out), maxOutputBytes), Err: fmt.Errorf("failed to run gopls check: %w", err)}
+	}
+
+	return lintResult{Output: truncate(string(out), maxOutputBytes)}
+}
+
+func runGolangCILint(cwd, target string) lintResult {
+	ctx, cancel := context.WithTimeout(context.Background(), diagnosticsTimeout)
+	defer cancel()
+
+	args := []string{
+		"run",
+		target,
+		"--show-stats=false",
+		"--output.text.path", "stdout",
+		"--output.text.colors=false",
+		"--output.text.print-issued-lines=false",
+	}
+	cmd := exec.CommandContext(ctx, "golangci-lint", args...)
+	cmd.Dir = cwd
+	out, err := cmd.CombinedOutput()
+
+	if ctx.Err() == context.DeadlineExceeded {
+		return lintResult{Err: fmt.Errorf("timed out after %s", diagnosticsTimeout)}
+	}
+
+	trimmed := truncate(string(out), maxOutputBytes)
+	if err == nil {
+		return lintResult{Output: trimmed}
+	}
+
+	exitErr, ok := err.(*exec.ExitError)
+	if ok && exitErr.ExitCode() == 1 {
+		return lintResult{Output: trimmed}
+	}
+
+	return lintResult{Output: trimmed, Err: fmt.Errorf("failed to run golangci-lint: %w", err)}
+}
+
+func formatToolResult(res lintResult, emptyFallback string) string {
+	var lines []string
+	if res.Err != nil {
+		lines = append(lines, "ERROR: "+res.Err.Error())
+	}
+	out := strings.TrimSpace(res.Output)
+	if out == "" {
+		if res.Err == nil {
+			if emptyFallback != "" {
+				lines = append(lines, emptyFallback)
+			}
+		}
+	} else {
+		lines = append(lines, out)
+	}
+	if len(lines) == 0 {
+		return emptyFallback
+	}
+	return strings.Join(lines, "\n")
+}
+
+func truncate(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max] + "\n... output truncated ..."
+}
+
+func countIssues(report string) (goplsCount, lintCount int) {
+	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]
+		for _, line := range strings.Split(goplsSection, "\n") {
+			line = strings.TrimSpace(line)
+			if line != "" && line != "[gopls]" && line != "No diagnostics." && !strings.HasPrefix(line, "#") {
+				goplsCount++
+			}
+		}
+	}
+
+	if lintStart != -1 && endTag != -1 {
+		lintSection := report[lintStart:endTag]
+		for _, line := range strings.Split(lintSection, "\n") {
+			line = strings.TrimSpace(line)
+			if line != "" && line != "[golangci-lint]" && line != "No lint issues." {
+				lintCount++
+			}
+		}
+	}
+
+	return goplsCount, lintCount
+}

.kit/extensions/subagent-monitor.go

@@ -0,0 +1,304 @@
+//go:build ignore
+
+// subagent-monitor — live horizontal widget strip for spawned subagents
+//
+// Subscribes to subagents spawned by the main Kit agent and displays a
+// single widget just above the input box. Each subagent occupies one column
+// in a side-by-side horizontal layout. Columns show scrolling real-time
+// output as the subagent works. When a subagent finishes its column is
+// removed automatically.
+//
+// Yaegi-safe design notes:
+// - No sync.Mutex (Yaegi has reflection issues with sync primitives)
+// - No channels in maps (Yaegi panics on range over map[string]chan)
+// - All ctx.* calls guarded with nil checks
+// - Simple data structures only
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"kit/ext"
+)
+
+// ---------------------------------------------------------------------------
+// Per-subagent state
+// ---------------------------------------------------------------------------
+
+type submonEntry struct {
+	id      int
+	callID  string
+	task    string
+	lines   []string
+	started time.Time
+	elapsed time.Duration
+}
+
+const (
+	submonColWidth = 34 // visible character width per column
+	submonMaxLines = 5  // scrolling output lines per column
+	submonColGap   = 2  // spaces between columns
+)
+
+// ---------------------------------------------------------------------------
+// Package-level state - all simple types
+// ---------------------------------------------------------------------------
+
+var (
+	submonCtx     ext.Context
+	submonHasCtx  bool
+	submonEntries []*submonEntry
+	submonNextID  int
+)
+
+func submonInit() {
+	submonEntries = nil
+	submonNextID = 1
+}
+
+// ---------------------------------------------------------------------------
+// String helpers
+// ---------------------------------------------------------------------------
+
+func submonPad(s string, w int) string {
+	r := []rune(s)
+	if len(r) >= w {
+		return string(r[:w])
+	}
+	return s + strings.Repeat(" ", w-len(r))
+}
+
+func submonTrunc(s string, w int) string {
+	r := []rune(s)
+	if len(r) <= w {
+		return s
+	}
+	if w <= 1 {
+		return "…"
+	}
+	return string(r[:w-1]) + "…"
+}
+
+// ---------------------------------------------------------------------------
+// Widget rendering
+// ---------------------------------------------------------------------------
+
+func submonRenderColumn(e *submonEntry) []string {
+	var rows []string
+
+	// Calculate elapsed time on-demand to avoid race conditions with ticker
+	elapsed := e.elapsed
+	if elapsed == 0 && !e.started.IsZero() {
+		elapsed = time.Since(e.started)
+	}
+	secs := int(elapsed.Seconds())
+	timeStr := fmt.Sprintf("%ds", secs)
+	taskMax := submonColWidth - len(timeStr) - 3
+	taskPart := submonTrunc(e.task, taskMax)
+	header := fmt.Sprintf("#%d %s  %s", e.id, taskPart, timeStr)
+	rows = append(rows, submonPad(header, submonColWidth))
+
+	display := e.lines
+	if len(display) > submonMaxLines {
+		display = display[len(display)-submonMaxLines:]
+	}
+	for _, l := range display {
+		rows = append(rows, submonPad("  "+submonTrunc(l, submonColWidth-2), submonColWidth))
+	}
+	for len(rows) < submonMaxLines+1 {
+		if len(rows) == 1 && len(e.lines) == 0 {
+			rows = append(rows, submonPad("  waiting…", submonColWidth))
+		} else {
+			rows = append(rows, strings.Repeat(" ", submonColWidth))
+		}
+	}
+	return rows
+}
+
+func submonBuildWidget() string {
+	if len(submonEntries) == 0 {
+		return ""
+	}
+
+	numCols := len(submonEntries)
+	numRows := submonMaxLines + 1
+	cols := make([][]string, numCols)
+	for i, e := range submonEntries {
+		rows := submonRenderColumn(e)
+		col := make([]string, numRows)
+		for j := 0; j < numRows; j++ {
+			if j < len(rows) {
+				col[j] = rows[j]
+			} else {
+				col[j] = strings.Repeat(" ", submonColWidth)
+			}
+		}
+		cols[i] = col
+	}
+
+	gap := strings.Repeat(" ", submonColGap)
+	var sb strings.Builder
+	for row := 0; row < numRows; row++ {
+		for ci := range cols {
+			if ci > 0 {
+				sb.WriteString(gap)
+			}
+			sb.WriteString(cols[ci][row])
+		}
+		if row < numRows-1 {
+			sb.WriteString("\n")
+		}
+	}
+	return sb.String()
+}
+
+func submonPushWidget() {
+	if !submonHasCtx {
+		return
+	}
+	if submonCtx.SetWidget == nil {
+		return
+	}
+
+	text := submonBuildWidget()
+	if len(submonEntries) == 0 {
+		if submonCtx.RemoveWidget != nil {
+			submonCtx.RemoveWidget("submon")
+		}
+		return
+	}
+	submonCtx.SetWidget(ext.WidgetConfig{
+		ID:        "submon",
+		Placement: ext.WidgetAbove,
+		Content:   ext.WidgetContent{Text: text},
+		Style:     ext.WidgetStyle{BorderColor: "#89b4fa"},
+		Priority:  0,
+	})
+}
+
+func submonAppendLine(e *submonEntry, line string) {
+	line = strings.TrimRight(line, "\r\n")
+	if strings.TrimSpace(line) == "" {
+		return
+	}
+	e.lines = append(e.lines, line)
+}
+
+// ---------------------------------------------------------------------------
+// Init
+// ---------------------------------------------------------------------------
+
+func Init(api ext.API) {
+	submonInit()
+
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		submonCtx = ctx
+		submonHasCtx = true
+		submonInit()
+		if ctx.RemoveWidget != nil {
+			ctx.RemoveWidget("submon")
+		}
+	})
+
+	api.OnAgentEnd(func(_ ext.AgentEndEvent, ctx ext.Context) {
+		submonCtx = ctx
+		submonHasCtx = true
+	})
+
+	// ── SubagentStart ────────────────────────────────────────────────────────
+	api.OnSubagentStart(func(e ext.SubagentStartEvent, ctx ext.Context) {
+		submonCtx = ctx
+		submonHasCtx = true
+
+		id := submonNextID
+		submonNextID++
+		entry := &submonEntry{
+			id:      id,
+			callID:  e.ToolCallID,
+			task:    e.Task,
+			started: time.Now(),
+		}
+		submonEntries = append(submonEntries, entry)
+
+		submonPushWidget()
+	})
+
+	// ── SubagentChunk ────────────────────────────────────────────────────────
+	api.OnSubagentChunk(func(e ext.SubagentChunkEvent, ctx ext.Context) {
+		submonCtx = ctx
+		submonHasCtx = true
+
+		var entry *submonEntry
+		for _, en := range submonEntries {
+			if en.callID == e.ToolCallID {
+				entry = en
+				break
+			}
+		}
+		if entry == nil {
+			return
+		}
+
+		switch e.ChunkType {
+		case "text":
+			for _, line := range strings.Split(e.Content, "\n") {
+				submonAppendLine(entry, line)
+			}
+		case "tool_call":
+			submonAppendLine(entry, "→ "+e.ToolName)
+		case "tool_execution_start":
+			submonAppendLine(entry, "⚙ "+e.ToolName)
+		case "tool_result":
+			if e.IsError {
+				submonAppendLine(entry, "✗ "+e.ToolName)
+			} else {
+				submonAppendLine(entry, "✓ "+e.ToolName)
+			}
+		}
+
+		submonPushWidget()
+	})
+
+	// ── SubagentEnd ──────────────────────────────────────────────────────────
+	api.OnSubagentEnd(func(e ext.SubagentEndEvent, ctx ext.Context) {
+		submonCtx = ctx
+		submonHasCtx = true
+
+		var entry *submonEntry
+		for _, en := range submonEntries {
+			if en.callID == e.ToolCallID {
+				entry = en
+				break
+			}
+		}
+		if entry != nil {
+			entry.elapsed = time.Since(entry.started)
+			if e.ErrorMsg != "" {
+				submonAppendLine(entry, "✗ "+submonTrunc(e.ErrorMsg, submonColWidth-2))
+			}
+		}
+
+		submonPushWidget()
+
+		// Remove the entry immediately (no goroutine to avoid races)
+		newEntries := submonEntries[:0]
+		for _, en := range submonEntries {
+			if en.callID != e.ToolCallID {
+				newEntries = append(newEntries, en)
+			}
+		}
+		submonEntries = newEntries
+		submonPushWidget()
+	})
+
+	// ── SessionShutdown ──────────────────────────────────────────────────────
+	api.OnSessionShutdown(func(_ ext.SessionShutdownEvent, ctx ext.Context) {
+		submonInit()
+		// Guard ctx access - may be nil during shutdown
+		if ctx.RemoveWidget != nil {
+			ctx.RemoveWidget("submon")
+		}
+	})
+}

.kit/prompts/acp-smoke-test.md

@@ -0,0 +1,37 @@
+---
+description: Run ACP smoke test against opencode/kimi-k2.5 to verify JSON-RPC stdio works
+---
+
+Run the ACP smoke test to verify the Kit ACP server works correctly over JSON-RPC stdio with streaming responses.
+
+## Steps
+
+1. Build the kit binary:
+   ```bash
+   go build -o output/kit ./cmd/kit
+   ```
+
+2. Run the smoke test Python script against opencode/kimi-k2.5:
+   ```bash
+   python3 scripts/acp_smoke_test.py
+   ```
+
+3. Verify the output shows:
+   - `session/new` returns a valid `sessionId`
+   - `session/prompt` streams `agent_thought_chunk` notifications (reasoning)
+   - `session/prompt` streams `agent_message_chunk` notifications (response)
+   - Final result has `stopReason: "end_turn"`
+   - `✓ SMOKE TEST PASSED` at the end
+
+4. If the test fails, check:
+   - `output/kit` binary exists and is executable
+   - `OPENCODE_API_KEY` or `OPENCODE_ZEN_API_KEY` environment variable is set
+   - `scripts/acp_smoke_test.py` exists
+   - The model `opencode/kimi-k2.5` is available (`kit models opencode | grep kimi-k2.5`)
+
+5. For testing with a different model, edit the script or set the `MODEL` variable:
+   ```bash
+   MODEL=anthropic/claude-sonnet-4-5 python3 scripts/acp_smoke_test.py
+   ```
+
+The smoke test exercises the full ACP protocol: session lifecycle, streaming notifications, and tool-free prompt completion.

.kit/prompts/commit-push.md

@@ -0,0 +1,30 @@
+---
+description: Stage, commit, and push changes with an auto-generated conventional commit message
+---
+
+Review the current git status and diff, then stage all changes, write a concise conventional commit message, commit, and push to the current branch.
+
+## Steps
+
+1. **Check status**: `git status` — understand what has changed
+2. **Review the diff**: `git diff` (and `git diff --cached` if anything is already staged) — read the actual changes
+3. **Stage everything**: `git add -A`
+4. **Craft the commit message** following Conventional Commits:
+   - Format: `<type>(<scope>): <short summary>`
+   - Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `build`
+   - Scope: optional, the subsystem affected (e.g. `ui`, `cmd`, `config`)
+   - Summary: imperative mood, lowercase, no trailing period, ≤72 chars
+   - Body: add a blank line then bullet points for non-trivial changes
+   - Do **not** include "Generated by" or similar noise
+5. **Commit**: `git commit -m "<message>"`
+6. **Push**: `git push`
+
+## Guidelines
+
+- Read the actual diff — do not guess from filenames alone
+- Prefer one well-scoped commit; do not split unless the changes are clearly unrelated
+- Keep the subject line under 72 characters
+- Use the body to explain *what* and *why*, not *how*
+- If there is nothing to commit, say so and stop
+
+$@

.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

@@ -0,0 +1,47 @@
+---
+description: Scaffold a new prompt template in .kit/prompts/
+---
+
+Create a new kit prompt template. The user wants a prompt that does: $@
+
+## What a prompt template is
+
+A prompt template is a `.md` file in `.kit/prompts/` (project-local) or `~/.kit/prompts/` (global).
+It becomes a `/slug` slash command in the kit input box — typed as `/filename` with optional arguments.
+
+## File format
+
+```
+---
+description: One-line description shown in autocomplete
+---
+
+Body text of the prompt. Use $@ for all user-supplied arguments,
+$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;
+  `$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
+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
+5. **Write the file** to `.kit/prompts/<slug>.md`
+6. **Confirm** by showing the final file content and the slash command that activates it
+
+## Guidelines
+
+- Keep prompts action-oriented — they should tell kit *what to do*, not just *what to think about*
+- Prefer concrete steps over vague instructions
+- A prompt that does one thing well beats one that tries to cover every edge case
+- If the workflow already exists as a prompt, suggest extending it instead of duplicating

.kit/prompts/release-tagger.md

@@ -0,0 +1,70 @@
+---
+description: Semantic version tagging workflow - analyzes commits and tags releases
+---
+
+# Release Tagging Workflow
+
+Tag a new version of this Go project following semantic versioning.
+
+## Steps
+
+1. **Fetch remote tags**: `git fetch --tags origin`
+
+2. **Find latest version**: `git tag -l | sort -V | tail -5` to see recent tags
+
+3. **Analyze changes since last tag**:
+   - `git log <latest-tag>..HEAD --oneline` - list commits
+   - `git diff <latest-tag>..HEAD --stat` - see file stats
+   - `git diff <latest-tag>..HEAD --name-only` - see changed files
+
+4. **Determine version bump** (Semantic Versioning):
+   - **MAJOR (X.0.0)**: Breaking API changes, incompatible modifications
+   - **MINOR (0.X.0)**: New features, backward-compatible additions
+   - **PATCH (0.0.X)**: Bug fixes, backward-compatible fixes
+   
+   Look for indicators:
+   - `feat:` or `feature:` commits → MINOR
+   - `fix:` or `bugfix:` commits → PATCH
+   - `breaking:` or `BREAKING CHANGE:` → MAJOR
+   - Breaking API changes in `pkg/` or public interfaces → MAJOR
+   - New commands, flags, or features → MINOR
+   - Documentation-only changes → PATCH (or skip)
+
+5. **Calculate new version**: Increment appropriate segment, reset lower segments to 0
+
+6. **Draft tag message**:
+   - Summarize key changes from commits
+   - Group by type (Features, Fixes, Breaking Changes)
+   - Keep concise but informative
+
+7. **Create annotated tag**: `git tag -a vX.Y.Z -m "vX.Y.Z - <summary>\n\n<detailed list>"`
+
+8. **Push tag**: `git push origin vX.Y.Z`
+
+## Guidelines
+
+- Always fetch remote tags first to avoid conflicts
+- Use annotated tags (`-a`) with descriptive messages
+- Follow semver strictly - when in doubt, prefer conservative bump (patch over minor)
+- For Go projects, changes to `pkg/` or exported APIs warrant careful version consideration
+- If no changes since last tag, suggest skipping the release
+- Include commit summaries in the tag message body
+
+## Example Tag Message Format
+
+```
+v0.30.1 - Bug fixes for model handling and UI improvements
+
+Fixes:
+- Properly handle think tags from Qwen/DeepSeek models
+- Handle custom provider model persistence and bare model names
+
+Improvements:
+- UI style refactoring and cleanup
+```
+
+Wait for the user to confirm the version and message before executing tag commands.
+
+---
+
+$@

AGENTS.md

@@ -1,22 +1,3 @@
-<!-- OPENSPEC:START -->
-# OpenSpec Instructions
-
-These instructions are for AI assistants working in this project.
-
-Always open `@/openspec/AGENTS.md` when the request:
-- Mentions planning or proposals (words like proposal, spec, change, plan)
-- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
-- Sounds ambiguous and you need the authoritative spec before coding
-
-Use `@/openspec/AGENTS.md` to learn:
-- How to create and apply change proposals
-- Spec format and conventions
-- Project structure and guidelines
-
-Keep this managed block so 'openspec update' can refresh the instructions.
-
-<!-- OPENSPEC:END -->
-
 # KIT Agent Guidelines
 
 ## Build/Test Commands
@@ -39,9 +20,101 @@ Keep this managed block so 'openspec update' can refresh the instructions.
 - Multi-provider LLM support via `llm.Provider` interface
 - MCP client-server for tool integration
 - Builtin servers: bash, fetch, todo, fs
+- **Extension system** (`internal/extensions/`): Yaegi-interpreted Go, 13 lifecycle events, custom tools/commands/widgets/overlays/editor interceptors
+- **TUI** (`internal/ui/`): Bubble Tea v2 parent-child model (`AppModel` → `InputComponent`, `StreamComponent`, etc.)
+- **Decoupling pattern**: `cmd/root.go` has converter functions (e.g. `widgetProviderForUI()`) that bridge `internal/extensions/` types to `internal/ui/` types — the UI never imports extensions directly
+- **Public SDK** (`pkg/kit/`): The public-facing Go SDK for embedding Kit as a library. See rules below.
+
+## Public SDK (`pkg/kit/`) Rules
+
+`pkg/kit/` is the **public API surface** consumed by external Go developers. All exported symbols, types, function names, and godoc comments in this package are part of the SDK contract.
+
+### No Dependency Name Leakage
+Internal dependency names (e.g. `charm.land/fantasy`, library-specific jargon) **must not** appear in:
+- **Exported function/method names** — use generic terms (`LLM`, `Provider`, `Message`) instead of library names
+- **Exported type names** — type aliases should use domain names (e.g. `LLMMessage`, not `FantasyMessage`)
+- **Godoc comments** on exported symbols — these are visible in `go doc` output and pkg.go.dev
+- **Struct field names and tags** on exported types
+
+Using dependency types directly in **function bodies** (private implementation) is fine — that's invisible to SDK consumers.
+
+### Naming Conventions for SDK Symbols
+- Type aliases re-exporting dependency types: use `LLM*` prefix (e.g. `LLMMessage`, `LLMUsage`, `LLMResponse`)
+- Conversion helpers: use `ConvertToLLM*` / `ConvertFromLLM*` (not the dependency name)
+- Provider queries: use `GetLLMProviders` (not `GetFantasyProviders`)
+- When wrapping internal methods, the `pkg/kit/` name should be dependency-agnostic even if the `internal/` method still uses the old name
+
+### Deprecation Pattern
+When renaming a public SDK symbol, keep the old name as a deprecated wrapper for one release cycle:
+```go
+// Deprecated: Use NewName instead.
+func OldName() { return NewName() }
+```
+
+## Key Patterns
+
+### Yaegi (Extension Interpreter) Gotchas
+- **No interfaces across boundary**: All extension-facing API types must be concrete structs, never interfaces. Yaegi crashes on interface wrapper generation.
+- **Function field bug**: Named function references assigned to struct fields return zero values across the interpreter boundary. Always use anonymous closure literals:
+  ```go
+  // WRONG: ctx.SetEditor(ext.EditorConfig{HandleKey: myHandler})
+  // RIGHT: ctx.SetEditor(ext.EditorConfig{HandleKey: func(k, t string) ext.EditorKeyAction { return myHandler(k, t) }})
+  ```
+- **Symbol exports**: Every new type exposed to extensions must be added to `internal/extensions/symbols.go`
+
+### BubbleTea Integration
+- **No `prog.Send()` from inside `Update()`**: Calling `prog.Send()` synchronously within a BubbleTea `Update()` handler deadlocks the event loop. Use `go appInstance.NotifyWidgetUpdate()` (async goroutine) instead.
+- **Height measurement**: `distributeHeight()` in `model.go` must measure using the same render path as `View()`. If an interceptor wraps rendering, measure with the wrapper too, or layout will mismatch.
+- **Channel-based prompts**: Extension prompt calls (PromptSelect, etc.) block on a `chan PromptResponse`. Extension slash commands run in dedicated goroutines (not `tea.Cmd`) to avoid stalling BubbleTea's Cmd scheduler.
+
+### Extension State Management
+- **Thread-safe maps on Runner**: Widget/header/footer/editor state lives on the Runner with `sync.RWMutex`, queried by UI via callbacks
+- **Context function fields**: The `Context` struct uses function fields (`Print func(string)`, `SetWidget func(WidgetConfig)`) wired by closures in `cmd/root.go`
+- **Package-level vars in extensions**: Yaegi supports package-level variables captured in closures — this is how extensions maintain state across event callbacks
+
+### Unicode in Widget Text
+- Widget content renders through `lipgloss.Style.Render()` which preserves ANSI escape codes
+- Use rune-based width calculations (`len([]rune(s))`) not byte length (`len(s)`) when aligning box-drawing characters or multi-byte symbols
+
+## Testing
+
+### Interactive TUI Testing with tmux
+Use tmux to test Kit interactively without blocking the agent:
+```bash
+tmux new-session -d -s kittest -x 120 -y 40 "output/kit -e examples/extensions/my-ext.go --no-session 2>kit_stderr.log"
+sleep 3
+tmux capture-pane -t kittest -p          # read screen
+tmux send-keys -t kittest '/command' Enter  # send input
+tmux kill-session -t kittest              # cleanup
+```
+
+### Non-Interactive Kit (Subprocess Spawning)
+Extensions can spawn Kit as a subprocess for sub-agent patterns:
+```bash
+kit --quiet --no-session --no-extensions --system-prompt /path/to/prompt.txt --model provider/model "question"
+```
+Positional args are the prompt. `@file` args attach file content. Key flags: `--quiet` (stdout only, no TUI), `--no-session` (ephemeral), `--no-extensions` (prevent recursive loading), `--system-prompt` (string or file path).
 
 ## External Repo Research
 - **ALWAYS use `btca`** to search external repos (e.g. iteratr, other reference codebases)
 - Never guess or manually search the filesystem for external projects
 - Example: `btca ask -r https://github.com/user/repo -q "How does X work?"`
 - See `.agents/skills/btca-cli/SKILL.md` for full btca usage
+
+## BTCA Configured Resources
+The following external repositories are configured in `btca.config.jsonc` for research:
+
+- bubbletea
+- lipgloss
+- bubbles
+- glamour
+- fantasy
+- catwalk
+- crush
+- pi
+- iteratr
+- yaegi
+- acp-go-sdk
+- opencode
+- herald
+- herald-md

AUTOSCROLL_FIX_SUMMARY.md

@@ -0,0 +1,80 @@
+# Autoscroll Fix - Final Summary
+
+## Root Cause
+
+The autoscroll was failing for streaming assistant messages due to a bug in how `GotoBottom()` calculated item heights.
+
+### The Problem
+
+1. **Reasoning blocks** (`StreamingMessageItem` with `role="reasoning"`) are **never cached** because they have live duration counters that update every render
+2. The `Height()` method returns `0` when `cachedRender == ""`
+3. `GotoBottom()` was calling:
+   ```go
+   itemHeight := item.Height()  // Returns 0 for reasoning
+   if itemHeight == 0 {
+       item.Render(s.width)  // Renders but doesn't cache (reasoning)
+       itemHeight = item.Height()  // Still returns 0!
+   }
+   ```
+4. This caused incorrect scroll position calculations, especially during reasoning → assistant transitions
+
+## The Solution
+
+Changed `GotoBottom()` and `AtBottom()` to calculate height **directly from the rendered string** instead of relying on the cached height:
+
+```go
+// OLD: item.Height() which checks cached render
+itemHeight := item.Height()
+if itemHeight == 0 {
+    item.Render(s.width)
+    itemHeight = item.Height()  // Still might be 0!
+}
+
+// NEW: Calculate from rendered string directly
+rendered := item.Render(s.width)
+itemHeight := strings.Count(rendered, "\n") + 1
+```
+
+This works for **all** items regardless of whether they cache their render or not.
+
+## Files Changed
+
+### `internal/ui/scrolllist.go`
+- **`GotoBottom()`**: Calculate height from rendered string (2 loops)
+- **`AtBottom()`**: Calculate height from rendered string (1 loop)
+
+### `internal/ui/model.go`
+- **`appendStreamingChunk()`**: For existing messages, call `GotoBottom()` directly (iteratr pattern)
+- **`refreshContent()`**: Simplified to only call `SetItems()` (removed redundant `GotoBottom()`)
+- **Bash streaming handler**: Removed redundant `GotoBottom()` after `refreshContent()`
+
+## Testing Results
+
+✅ **Test prompt**: "explore this repo"
+
+**Before fix**:
+- Autoscroll stopped after reasoning block completed
+- Viewport stuck showing end of reasoning ("Thought for 203ms")
+- Assistant response streamed off-screen below
+
+**After fix**:
+- Autoscroll works throughout reasoning block
+- Autoscroll continues during reasoning → assistant transition  
+- Viewport stays at bottom showing latest assistant content
+- Final position shows end of response (build commands section)
+
+## Behavior Verified
+
+1. ✅ Streaming text auto-scrolls to bottom
+2. ✅ Works across reasoning → assistant transition
+3. ✅ Manual scroll up (PgUp) disables autoscroll
+4. ✅ Scroll to bottom (Alt+End) re-enables autoscroll
+5. ✅ Accurate positioning with no offset errors
+
+## Performance Note
+
+The fix calls `Render()` on all items during `GotoBottom()` calculations. This is acceptable because:
+- `Render()` is already optimized with caching for non-reasoning items
+- `GotoBottom()` is only called during content updates (not every frame)
+- Reasoning blocks need to render anyway for live duration updates
+- This matches iteratr's approach of ensuring items are rendered before height calculations

btca.config.jsonc

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

cmd/acp.go

@@ -0,0 +1,162 @@
+package cmd
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/charmbracelet/log"
+	acp "github.com/coder/acp-go-sdk"
+
+	"github.com/mark3labs/kit/internal/acpserver"
+	"github.com/spf13/cobra"
+)
+
+var acpCmd = &cobra.Command{
+	Use:   "acp",
+	Short: "Start Kit as an ACP agent server",
+	Long: `Start Kit as an ACP (Agent Client Protocol) agent server.
+
+Communicates over stdio (stdin/stdout) using JSON-RPC 2.0 with
+newline-delimited JSON, compatible with OpenCode and other ACP clients.
+
+The server exposes Kit's LLM execution, tool system, and session
+management via the Agent Client Protocol. Sessions are persisted
+to Kit's standard JSONL session files.`,
+	RunE: runACP,
+}
+
+func init() {
+	rootCmd.AddCommand(acpCmd)
+}
+
+func runACP(cmd *cobra.Command, _ []string) error {
+	// Create the ACP agent implementation.
+	agent := acpserver.NewAgent()
+	defer agent.Close()
+
+	// Create the stdio connection. The SDK reads JSON-RPC from stdin and
+	// writes responses to stdout. We wrap stdin with a normalizer that
+	// fills in optional fields the SDK's generated validation requires
+	// (e.g. mcpServers) so clients that omit them still work.
+	conn := acp.NewAgentSideConnection(agent, os.Stdout, newACPNormalizer(os.Stdin))
+
+	// Wire the connection back to the agent so it can send session updates.
+	agent.SetAgentConnection(conn)
+
+	// Enable debug logging to stderr if requested.
+	if debugMode {
+		conn.SetLogger(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
+			Level: slog.LevelDebug,
+		})))
+		// Also set charmbracelet/log level for acpserver package logging
+		log.SetLevel(log.DebugLevel)
+	}
+
+	// Wait for either the client to disconnect or a signal.
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case <-conn.Done():
+		fmt.Fprintln(os.Stderr, "kit: ACP client disconnected")
+	case sig := <-sigCh:
+		fmt.Fprintf(os.Stderr, "kit: received %s, shutting down\n", sig)
+	}
+
+	return nil
+}
+
+// acpNormalizer wraps an io.Reader carrying newline-delimited JSON-RPC and
+// patches incoming messages so that fields the SDK validates as required —
+// but that some clients (e.g. Zed) omit — are defaulted. This avoids
+// InvalidParams errors without forking the SDK.
+type acpNormalizer struct {
+	scanner *bufio.Scanner
+	buf     bytes.Buffer // leftover bytes from the last normalized line
+}
+
+func newACPNormalizer(r io.Reader) *acpNormalizer {
+	const maxMsg = 10 * 1024 * 1024 // 10 MB, matches SDK buffer
+	s := bufio.NewScanner(r)
+	s.Buffer(make([]byte, 0, 1024*1024), maxMsg)
+	return &acpNormalizer{scanner: s}
+}
+
+// Read satisfies io.Reader. It feeds one normalized JSON line (plus newline)
+// per underlying scan, buffering across short caller reads.
+func (n *acpNormalizer) Read(p []byte) (int, error) {
+	// Drain any leftover bytes from the previous line first.
+	if n.buf.Len() > 0 {
+		return n.buf.Read(p)
+	}
+
+	if !n.scanner.Scan() {
+		if err := n.scanner.Err(); err != nil {
+			return 0, err
+		}
+		return 0, io.EOF
+	}
+
+	line := n.scanner.Bytes()
+	normalized := normalizeACPLine(line)
+	n.buf.Write(normalized)
+	n.buf.WriteByte('\n')
+	return n.buf.Read(p)
+}
+
+// normalizeACPLine ensures session/new and session/load params contain an
+// mcpServers array. Returns the original line unchanged for all other methods.
+func normalizeACPLine(line []byte) []byte {
+	// Quick check: if it already contains mcpServers, nothing to do.
+	if bytes.Contains(line, []byte(`"mcpServers"`)) {
+		return line
+	}
+
+	// Only bother parsing if the method could be session/new or session/load.
+	if !bytes.Contains(line, []byte(`"session/new"`)) &&
+		!bytes.Contains(line, []byte(`"session/load"`)) {
+		return line
+	}
+
+	var msg struct {
+		JSONRPC string          `json:"jsonrpc"`
+		ID      json.RawMessage `json:"id,omitempty"`
+		Method  string          `json:"method"`
+		Params  json.RawMessage `json:"params,omitempty"`
+	}
+	if err := json.Unmarshal(line, &msg); err != nil {
+		return line
+	}
+	if msg.Method != "session/new" && msg.Method != "session/load" {
+		return line
+	}
+
+	// Patch params to include mcpServers: [].
+	var params map[string]json.RawMessage
+	if err := json.Unmarshal(msg.Params, &params); err != nil {
+		return line
+	}
+	if _, ok := params["mcpServers"]; ok {
+		return line
+	}
+	params["mcpServers"] = json.RawMessage(`[]`)
+
+	patched, err := json.Marshal(params)
+	if err != nil {
+		return line
+	}
+	msg.Params = patched
+
+	out, err := json.Marshal(msg)
+	if err != nil {
+		return line
+	}
+	return out
+}

cmd/auth.go

@@ -1,11 +1,15 @@
 package cmd
 
 import (
-	"bufio"
+	"context"
 	"fmt"
+	"net"
+	"net/http"
 	"os"
 	"strings"
+	"time"
 
+	"charm.land/huh/v2"
 	"github.com/mark3labs/kit/internal/auth"
 	kit "github.com/mark3labs/kit/pkg/kit"
 	"github.com/spf13/cobra"
@@ -14,7 +18,7 @@ import (
 // authCmd represents the auth command for managing AI provider authentication.
 // This command provides subcommands for login, logout, and status checking
 // of authentication credentials for various AI providers, with OAuth support
-// for providers like Anthropic.
+// for providers like Anthropic and OpenAI.
 var authCmd = &cobra.Command{
 	Use:   "auth",
 	Short: "Manage authentication credentials for AI providers",
@@ -25,9 +29,11 @@ using OAuth flows. Stored credentials take precedence over environment variables
 
 Available providers:
   - anthropic: Anthropic Claude API (OAuth)
+  - openai:    OpenAI API (OAuth and API key)
 
 Examples:
   kit auth login anthropic
+  kit auth login openai
   kit auth logout anthropic
   kit auth status`,
 }
@@ -46,9 +52,11 @@ environment variables when making API calls.
 
 Available providers:
   - anthropic: Anthropic Claude API (OAuth)
+  - openai:    OpenAI ChatGPT Plus/Pro (Codex OAuth)
 
 Example:
-  kit auth login anthropic`,
+  kit auth login anthropic
+  kit auth login openai`,
 	Args: cobra.ExactArgs(1),
 	RunE: runAuthLogin,
 }
@@ -61,14 +69,16 @@ var authLogoutCmd = &cobra.Command{
 	Short: "Remove stored authentication credentials for a provider",
 	Long: `Remove stored authentication credentials for an AI provider.
 
-This will delete the stored API key for the specified provider. You will need
-to use environment variables or command-line flags for authentication after logout.
+This will delete the stored API key or OAuth credentials for the specified provider. 
+You will need to use environment variables or command-line flags for authentication after logout.
 
 Available providers:
   - anthropic: Anthropic Claude API
+  - openai:    OpenAI API
 
 Example:
-  kit auth logout anthropic`,
+  kit auth logout anthropic
+  kit auth logout openai`,
 	Args: cobra.ExactArgs(1),
 	RunE: runAuthLogout,
 }
@@ -101,8 +111,10 @@ func runAuthLogin(cmd *cobra.Command, args []string) error {
 	switch provider {
 	case "anthropic":
 		return loginAnthropic()
+	case "openai":
+		return loginOpenAI()
 	default:
-		return fmt.Errorf("unsupported provider: %s. Available providers: anthropic", provider)
+		return fmt.Errorf("unsupported provider: %s. Available providers: anthropic, openai", provider)
 	}
 }
 
@@ -112,8 +124,10 @@ func runAuthLogout(cmd *cobra.Command, args []string) error {
 	switch provider {
 	case "anthropic":
 		return logoutAnthropic()
+	case "openai":
+		return logoutOpenAI()
 	default:
-		return fmt.Errorf("unsupported provider: %s. Available providers: anthropic", provider)
+		return fmt.Errorf("unsupported provider: %s. Available providers: anthropic, openai", provider)
 	}
 }
 
@@ -157,8 +171,44 @@ func runAuthStatus(cmd *cobra.Command, args []string) error {
 		}
 	}
 
+	// Check OpenAI credentials
+	fmt.Print("\nOpenAI: ")
+	if hasOpenAICreds, err := cm.HasOpenAICredentials(); err != nil {
+		fmt.Printf("Error checking credentials: %v\n", err)
+	} else if hasOpenAICreds {
+		if creds, err := cm.GetOpenAICredentials(); err != nil {
+			fmt.Printf("Error reading credentials: %v\n", err)
+		} else {
+			authType := "API Key"
+			status := "✓ Authenticated"
+
+			if creds.Type == "oauth" {
+				authType = "OAuth (ChatGPT/Codex)"
+				if creds.IsExpired() {
+					status = "⚠️  Token expired (will refresh automatically)"
+				} else if creds.NeedsRefresh() {
+					status = "⚠️  Token expires soon (will refresh automatically)"
+				}
+			}
+
+			accountInfo := ""
+			if creds.Type == "oauth" && creds.AccountID != "" {
+				accountInfo = fmt.Sprintf(" [%s]", creds.AccountID)
+			}
+
+			fmt.Printf("%s (%s%s, stored %s)\n", status, authType, accountInfo, creds.CreatedAt.Format("2006-01-02 15:04:05"))
+		}
+	} else {
+		fmt.Println("✗ Not authenticated")
+		// Check if environment variable is set
+		if os.Getenv("OPENAI_API_KEY") != "" {
+			fmt.Println("  (OPENAI_API_KEY environment variable is set)")
+		}
+	}
+
 	fmt.Println("\nTo authenticate with a provider:")
 	fmt.Println("  kit auth login anthropic")
+	fmt.Println("  kit auth login openai")
 
 	return nil
 }
@@ -171,14 +221,15 @@ func loginAnthropic() error {
 
 	// Check if already authenticated
 	if hasAuth, err := cm.HasAnthropicCredentials(); err == nil && hasAuth {
-		fmt.Print("You are already authenticated with Anthropic. Do you want to re-authenticate? (y/N): ")
-		reader := bufio.NewReader(os.Stdin)
-		response, err := reader.ReadString('\n')
-		if err != nil {
-			return fmt.Errorf("failed to read response: %w", err)
-		}
-		response = strings.TrimSpace(strings.ToLower(response))
-		if response != "y" && response != "yes" {
+		var reauth bool
+		err := huh.NewConfirm().
+			Title("You are already authenticated with Anthropic").
+			Description("Do you want to re-authenticate?").
+			Affirmative("Yes").
+			Negative("No").
+			Value(&reauth).
+			Run()
+		if err != nil || !reauth {
 			fmt.Println("Authentication cancelled.")
 			return nil
 		}
@@ -204,10 +255,13 @@ func loginAnthropic() error {
 
 	// Wait for user to complete OAuth flow
 	fmt.Println("After authorizing the application, you'll receive an authorization code.")
-	fmt.Print("Please enter the authorization code: ")
 
-	reader := bufio.NewReader(os.Stdin)
-	code, err := reader.ReadString('\n')
+	var code string
+	err = huh.NewInput().
+		Title("Authorization code").
+		Description("Paste the code from your browser").
+		Value(&code).
+		Run()
 	if err != nil {
 		return fmt.Errorf("failed to read authorization code: %w", err)
 	}
@@ -255,15 +309,15 @@ func logoutAnthropic() error {
 	}
 
 	// Confirm logout
-	fmt.Print("Are you sure you want to remove your Anthropic credentials? (y/N): ")
-	reader := bufio.NewReader(os.Stdin)
-	response, err := reader.ReadString('\n')
-	if err != nil {
-		return fmt.Errorf("failed to read response: %w", err)
-	}
-
-	response = strings.TrimSpace(strings.ToLower(response))
-	if response != "y" && response != "yes" {
+	var confirm bool
+	err = huh.NewConfirm().
+		Title("Remove Anthropic credentials").
+		Description("Are you sure you want to remove your stored credentials?").
+		Affirmative("Yes").
+		Negative("No").
+		Value(&confirm).
+		Run()
+	if err != nil || !confirm {
 		fmt.Println("Logout cancelled.")
 		return nil
 	}
@@ -278,3 +332,246 @@ func logoutAnthropic() error {
 
 	return nil
 }
+
+func loginOpenAI() error {
+	cm, err := kit.NewCredentialManager()
+	if err != nil {
+		return fmt.Errorf("failed to initialize credential manager: %w", err)
+	}
+
+	// Check if already authenticated
+	if hasAuth, err := cm.HasOpenAICredentials(); err == nil && hasAuth {
+		var reauth bool
+		err := huh.NewConfirm().
+			Title("You are already authenticated with OpenAI (ChatGPT/Codex)").
+			Description("Do you want to re-authenticate?").
+			Affirmative("Yes").
+			Negative("No").
+			Value(&reauth).
+			Run()
+		if err != nil || !reauth {
+			fmt.Println("Authentication cancelled.")
+			return nil
+		}
+	}
+
+	// Create OAuth client
+	client := auth.NewOpenAIOAuthClient()
+
+	// Generate authorization URL
+	fmt.Println("🔐 Starting OAuth authentication with OpenAI (ChatGPT/Codex)...")
+	fmt.Println("This will open your browser to authenticate with your ChatGPT account.")
+	fmt.Println()
+
+	authData, err := client.GetAuthorizationURL()
+	if err != nil {
+		return fmt.Errorf("failed to generate authorization URL: %w", err)
+	}
+
+	// Start local callback server
+	callbackServer, err := startOpenAICallbackServer(authData.State)
+	if err != nil {
+		fmt.Printf("⚠️  Could not start local callback server: %v\n", err)
+		fmt.Println("Falling back to manual code entry.")
+	}
+	if callbackServer != nil {
+		defer callbackServer.Close()
+	}
+
+	// Display URL and try to open browser
+	fmt.Println("📱 Opening your browser for authentication...")
+	fmt.Println("If the browser doesn't open automatically, please visit this URL:")
+	fmt.Printf("\n%s\n\n", authData.URL)
+
+	// Try to open browser
+	auth.TryOpenBrowser(authData.URL)
+
+	// Wait for callback or manual input
+	var code string
+	if callbackServer != nil {
+		fmt.Println("Waiting for browser authentication...")
+		select {
+		case callbackCode := <-callbackServer.CodeChan:
+			if callbackCode != "" {
+				code = callbackCode
+				fmt.Println("✓ Received authorization code from browser callback.")
+			}
+		case <-time.After(2 * time.Minute):
+			fmt.Println("\n⏱️  Timeout waiting for browser callback.")
+			callbackServer.Close()
+		}
+	}
+
+	// If no code from callback, prompt for manual entry
+	if code == "" {
+		fmt.Println("\nAfter authorizing, paste the callback URL or authorization code below.")
+		fmt.Println("(The callback URL will look like: http://localhost:1455/auth/callback?code=...&state=...)")
+		fmt.Println()
+
+		var input string
+		err = huh.NewInput().
+			Title("Callback URL or Code").
+			Description("Paste the full callback URL or just the authorization code").
+			Value(&input).
+			Run()
+		if err != nil {
+			return fmt.Errorf("failed to read input: %w", err)
+		}
+		input = strings.TrimSpace(input)
+
+		if input == "" {
+			return fmt.Errorf("authorization code cannot be empty")
+		}
+
+		// Parse the input (could be full URL or just code)
+		parsedCode, parsedState := auth.ParseOpenAIAuthorizationInput(input)
+		if parsedCode == "" {
+			return fmt.Errorf("could not extract authorization code from input")
+		}
+
+		// Validate state if provided
+		if parsedState != "" && parsedState != authData.State {
+			return fmt.Errorf("state mismatch - possible security issue")
+		}
+		code = parsedCode
+	}
+
+	// Exchange code for tokens
+	fmt.Println("\n🔄 Exchanging authorization code for access token...")
+	creds, err := client.ExchangeCode(code, authData.Verifier)
+	if err != nil {
+		return fmt.Errorf("failed to exchange authorization code: %w", err)
+	}
+
+	// Store the credentials
+	if err := cm.SetOpenAIOAuthCredentials(creds); err != nil {
+		return fmt.Errorf("failed to store credentials: %w", err)
+	}
+
+	fmt.Println("✅ Successfully authenticated with OpenAI (ChatGPT/Codex)!")
+	fmt.Printf("📁 Credentials stored in: %s\n", cm.GetCredentialsPath())
+	fmt.Printf("👤 Account ID: %s\n", creds.AccountID)
+	fmt.Println("\n🎉 Your OAuth credentials will now be used for OpenAI API calls.")
+	fmt.Println("💡 You can check your authentication status with: kit auth status")
+
+	return nil
+}
+
+// callbackServer holds the HTTP server and channel for receiving the OAuth callback
+type callbackServer struct {
+	Server   *http.Server
+	CodeChan chan string
+	State    string
+}
+
+// Close shuts down the callback server
+func (cs *callbackServer) Close() {
+	if cs.Server != nil {
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		_ = cs.Server.Shutdown(ctx)
+	}
+}
+
+// startOpenAICallbackServer starts a local HTTP server to receive the OAuth callback
+func startOpenAICallbackServer(expectedState string) (*callbackServer, error) {
+	codeChan := make(chan string, 1)
+
+	mux := http.NewServeMux()
+	server := &http.Server{
+		Addr:    "127.0.0.1:1455",
+		Handler: mux,
+	}
+
+	mux.HandleFunc("/auth/callback", func(w http.ResponseWriter, r *http.Request) {
+		// Check state
+		state := r.URL.Query().Get("state")
+		if state != expectedState {
+			http.Error(w, "State mismatch", http.StatusBadRequest)
+			return
+		}
+
+		code := r.URL.Query().Get("code")
+		if code == "" {
+			http.Error(w, "Missing authorization code", http.StatusBadRequest)
+			return
+		}
+
+		// Send code to channel
+		select {
+		case codeChan <- code:
+		default:
+		}
+
+		// Return success page
+		w.Header().Set("Content-Type", "text/html")
+		w.WriteHeader(http.StatusOK)
+		_, _ = fmt.Fprintf(w, `<!DOCTYPE html>
+<html>
+<head><title>Authentication Successful</title></head>
+<body style="font-family: sans-serif; text-align: center; padding: 50px;">
+<h1>✓ Authentication Successful</h1>
+<p>You can close this window and return to the terminal.</p>
+</body>
+</html>`)
+	})
+
+	// Try to start server
+	listener, err := net.Listen("tcp", "127.0.0.1:1455")
+	if err != nil {
+		return nil, fmt.Errorf("port 1455 not available: %w", err)
+	}
+	_ = listener.Close()
+
+	go func() {
+		_ = server.ListenAndServe()
+	}()
+
+	return &callbackServer{
+		Server:   server,
+		CodeChan: codeChan,
+		State:    expectedState,
+	}, nil
+}
+
+func logoutOpenAI() error {
+	cm, err := kit.NewCredentialManager()
+	if err != nil {
+		return fmt.Errorf("failed to initialize credential manager: %w", err)
+	}
+
+	// Check if authenticated
+	hasAuth, err := cm.HasOpenAICredentials()
+	if err != nil {
+		return fmt.Errorf("failed to check authentication status: %w", err)
+	}
+
+	if !hasAuth {
+		fmt.Println("You are not currently authenticated with OpenAI.")
+		return nil
+	}
+
+	// Confirm logout
+	var confirm bool
+	err = huh.NewConfirm().
+		Title("Remove OpenAI credentials").
+		Description("Are you sure you want to remove your stored credentials?").
+		Affirmative("Yes").
+		Negative("No").
+		Value(&confirm).
+		Run()
+	if err != nil || !confirm {
+		fmt.Println("Logout cancelled.")
+		return nil
+	}
+
+	// Remove credentials
+	if err := cm.RemoveOpenAICredentials(); err != nil {
+		return fmt.Errorf("failed to remove credentials: %w", err)
+	}
+
+	fmt.Println("✓ Successfully logged out from OpenAI!")
+	fmt.Println("You will need to use environment variables or command-line flags for authentication.")
+
+	return nil
+}

cmd/install.go

@@ -0,0 +1,225 @@
+package cmd
+
+import (
+	"fmt"
+	"os/exec"
+
+	"github.com/charmbracelet/log"
+	"github.com/mark3labs/kit/internal/extensions"
+	"github.com/spf13/cobra"
+)
+
+var (
+	installLocalFlag     bool
+	installUpdateFlag    bool
+	installUninstallFlag bool
+	installAllFlag       bool
+)
+
+var installCmd = &cobra.Command{
+	Use:   "install <git-url>",
+	Short: "Install extensions from git repositories",
+	Long: `Install extensions from git repositories.
+
+The install command downloads and installs Kit extensions from git repositories.
+Extensions are stored in the global extensions directory by default, or in the
+project's .kit/git/ directory when using the --local flag.
+
+When a repo contains multiple extensions, an interactive multi-select is shown
+so you can choose which to install. Use --all to skip selection and install everything.
+
+Supported URL formats:
+  - github.com/user/repo (shorthand, defaults to HTTPS)
+  - git:github.com/user/repo
+  - https://github.com/user/repo
+  - ssh://git@github.com/user/repo
+  - git@github.com:user/repo
+
+You can pin to a specific version, tag, or commit using @:
+  - github.com/user/repo@v1.0.0
+  - github.com/user/repo@main
+  - github.com/user/repo@abc1234
+
+Examples:
+  kit install github.com/user/my-extension
+  kit install github.com/user/my-extension@v1.0.0
+  kit install github.com/user/my-extension --local
+  kit install github.com/user/collection --all`,
+	Args: cobra.ExactArgs(1),
+	RunE: runInstall,
+}
+
+func init() {
+	installCmd.Flags().BoolVarP(&installLocalFlag, "local", "l", false, "Install to project-local .kit/git/ directory")
+	installCmd.Flags().BoolVarP(&installUpdateFlag, "update", "u", false, "Update an already-installed package")
+	installCmd.Flags().BoolVar(&installUninstallFlag, "uninstall", false, "Remove an installed package")
+	installCmd.Flags().BoolVar(&installAllFlag, "all", false, "Install all extensions without prompting")
+
+	rootCmd.AddCommand(installCmd)
+}
+
+func runInstall(cmd *cobra.Command, args []string) error {
+	sourceStr := args[0]
+
+	// Check that git is available
+	if _, err := exec.LookPath("git"); err != nil {
+		return fmt.Errorf("git is not installed or not in PATH")
+	}
+
+	// Parse the source
+	source, err := extensions.ParseGitSource(sourceStr)
+	if err != nil {
+		return fmt.Errorf("invalid source: %w", err)
+	}
+
+	// Determine scope
+	scope := extensions.ScopeGlobal
+	if installLocalFlag {
+		scope = extensions.ScopeProject
+	}
+
+	installer := extensions.NewInstaller(".")
+
+	// Handle uninstall
+	if installUninstallFlag {
+		return runUninstall(installer, source, scope)
+	}
+
+	// Handle update
+	if installUpdateFlag {
+		return runUpdate(installer, source, scope)
+	}
+
+	// Handle install
+	return runInstallPackage(installer, source, scope)
+}
+
+func runInstallPackage(installer *extensions.Installer, source *extensions.GitSource, scope extensions.InstallScope) error {
+	// Check if already installed
+	existingScope, installed := installer.IsInstalled(source)
+	if installed {
+		return fmt.Errorf("extension already installed (scope: %s). Use --update to update or --uninstall to remove", existingScope)
+	}
+
+	// Preview extensions to decide if we need multi-select
+	previews, tempDir, err := installer.PreviewExtensions(source)
+	if err != nil {
+		return fmt.Errorf("previewing extensions: %w", err)
+	}
+	defer extensions.CleanupTempDir(tempDir)
+
+	if len(previews) == 0 {
+		return fmt.Errorf("no extensions found in %s", source.String())
+	}
+
+	scopeStr := "globally"
+	if scope == extensions.ScopeProject {
+		scopeStr = "locally in .kit/git/"
+	}
+
+	// Single extension or --all flag: install everything directly
+	if len(previews) == 1 || installAllFlag {
+		if err := installer.Install(source, scope); err != nil {
+			return fmt.Errorf("install failed: %w", err)
+		}
+
+		if source.Pinned {
+			fmt.Printf("Installed %s at %s %s\n", source.String(), source.Ref, scopeStr)
+		} else {
+			fmt.Printf("Installed %d extension(s) from %s %s\n", len(previews), source.String(), scopeStr)
+		}
+
+		log.Info("extension installed", "source", source.String(), "scope", scope)
+		return nil
+	}
+
+	// Multiple extensions: show interactive selection
+	includePaths, err := multiSelectForInstall(previews)
+	if err != nil {
+		if err.Error() == "selection cancelled" || err.Error() == "no extensions selected" {
+			fmt.Println("Install cancelled.")
+			return nil
+		}
+		return fmt.Errorf("selection failed: %w", err)
+	}
+
+	if err := installer.InstallWithInclude(source, scope, includePaths); err != nil {
+		return fmt.Errorf("install failed: %w", err)
+	}
+
+	fmt.Printf("Installed %d extension(s) from %s %s\n", len(includePaths), source.String(), scopeStr)
+	for _, path := range includePaths {
+		fmt.Printf("  - %s\n", path)
+	}
+
+	log.Info("extension installed", "source", source.String(), "scope", scope, "selected", len(includePaths))
+	return nil
+}
+
+func runUpdate(installer *extensions.Installer, source *extensions.GitSource, scope extensions.InstallScope) error {
+	// Find the installed package
+	existingScope, installed := installer.IsInstalled(source)
+	if !installed {
+		// Try to find with wildcard (no version)
+		entry, foundScope, err := extensions.FindInManifest(source.Identity())
+		if err != nil || entry == nil {
+			return fmt.Errorf("extension not installed: %s", source.Identity())
+		}
+		// Parse the found entry's source
+		foundSource, err := extensions.ParseGitSource(entry.Source)
+		if err != nil {
+			return fmt.Errorf("failed to parse installed source: %w", err)
+		}
+		existingScope = foundScope
+		source = foundSource
+	}
+
+	// Override scope if specified
+	if installLocalFlag && scope != existingScope {
+		return fmt.Errorf("extension installed in %s scope, cannot update with --local flag", existingScope)
+	}
+	scope = existingScope
+
+	// Check if pinned
+	if source.Pinned {
+		fmt.Printf("Skipping %s (pinned at %s)\n", source.Identity(), source.Ref)
+		return nil
+	}
+
+	// Update
+	if err := installer.Update(source, scope); err != nil {
+		return fmt.Errorf("update failed: %w", err)
+	}
+
+	fmt.Printf("Updated %s\n", source.Identity())
+	log.Info("extension updated", "source", source.Identity(), "scope", scope)
+	return nil
+}
+
+func runUninstall(installer *extensions.Installer, source *extensions.GitSource, scope extensions.InstallScope) error {
+	// Find where it's installed (ignore scope flag for uninstall - remove from wherever it exists)
+	existingScope, installed := installer.IsInstalled(source)
+	if !installed {
+		// Try to find in manifests
+		entry, foundScope, err := extensions.FindInManifest(source.Identity())
+		if err != nil || entry == nil {
+			return fmt.Errorf("extension not installed: %s", source.Identity())
+		}
+		existingScope = foundScope
+		// Parse the found entry's source
+		foundSource, err := extensions.ParseGitSource(entry.Source)
+		if err != nil {
+			return fmt.Errorf("failed to parse installed source: %w", err)
+		}
+		source = foundSource
+	}
+
+	// Uninstall from the scope where it's installed
+	if err := installer.Uninstall(source, existingScope); err != nil {
+		return fmt.Errorf("uninstall failed: %w", err)
+	}
+
+	fmt.Printf("Uninstalled %s from %s scope\n", source.Identity(), existingScope)
+	log.Info("extension uninstalled", "source", source.Identity(), "scope", existingScope)
+	return nil
+}

cmd/install_multiselect.go

@@ -0,0 +1,70 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"charm.land/huh/v2"
+	"github.com/charmbracelet/log"
+	"github.com/mark3labs/kit/internal/extensions"
+)
+
+// multiSelectForInstall runs a multi-select prompt for extension selection.
+// Returns the selected extension paths, or an error if cancelled.
+func multiSelectForInstall(previews []extensions.ExtensionPreview) ([]string, error) {
+	if len(previews) == 0 {
+		return nil, fmt.Errorf("no extensions to select")
+	}
+
+	// Non-interactive: select all
+	if !isInteractive() {
+		log.Info("Non-interactive mode, selecting all extensions")
+		paths := make([]string, len(previews))
+		for i, p := range previews {
+			paths[i] = p.Path
+		}
+		return paths, nil
+	}
+
+	// Single extension: just return it
+	if len(previews) == 1 {
+		return []string{previews[0].Path}, nil
+	}
+
+	// Build options for huh MultiSelect
+	options := make([]huh.Option[string], len(previews))
+	for i, p := range previews {
+		label := fmt.Sprintf("%s  %s", p.Name, p.Path)
+		options[i] = huh.NewOption(label, p.Path).Selected(true)
+	}
+
+	var selected []string
+
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewMultiSelect[string]().
+				Title("Select extensions to install").
+				Options(options...).
+				Value(&selected),
+		),
+	)
+
+	if err := form.Run(); err != nil {
+		return nil, fmt.Errorf("selection cancelled")
+	}
+
+	if len(selected) == 0 {
+		return nil, fmt.Errorf("no extensions selected")
+	}
+
+	return selected, nil
+}
+
+// isInteractive checks if the terminal is interactive.
+func isInteractive() bool {
+	fi, err := os.Stdout.Stat()
+	if err != nil {
+		return false
+	}
+	return (fi.Mode() & os.ModeCharDevice) != 0
+}

cmd/models.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"sort"
 
+	"github.com/mark3labs/kit/internal/models"
 	kit "github.com/mark3labs/kit/pkg/kit"
 	"github.com/spf13/cobra"
 )
@@ -47,11 +48,14 @@ func runModels(_ *cobra.Command, args []string) error {
 }
 
 func printAllProviders(showAll bool) error {
+	// Reload the registry to pick up any custom models from config
+	models.ReloadGlobalRegistry()
+
 	var providerIDs []string
 	if showAll {
 		providerIDs = kit.GetSupportedProviders()
 	} else {
-		providerIDs = kit.GetFantasyProviders()
+		providerIDs = kit.GetLLMProviders()
 	}
 	sort.Strings(providerIDs)
 
@@ -98,6 +102,9 @@ func printAllProviders(showAll bool) error {
 }
 
 func printProvider(provider string) error {
+	// Reload the registry to pick up any custom models from config
+	models.ReloadGlobalRegistry()
+
 	m, err := kit.GetModelsForProvider(provider)
 	if err != nil {
 		return fmt.Errorf("unknown provider %q. Run 'kit models' to see all providers", provider)

cmd/setup.go

@@ -3,7 +3,6 @@ package cmd
 import (
 	"strings"
 
-	"github.com/mark3labs/kit/internal/agent"
 	"github.com/mark3labs/kit/internal/app"
 	"github.com/mark3labs/kit/internal/config"
 	"github.com/mark3labs/kit/internal/ui"
@@ -12,9 +11,9 @@ import (
 )
 
 // CollectAgentMetadata extracts model display info and tool/server name lists
-// from the agent, used to populate app.Options and UI setup.
+// from the Kit instance, used to populate app.Options and UI setup.
 // It also returns the number of MCP tools and extension tools separately.
-func CollectAgentMetadata(mcpAgent *agent.Agent, mcpConfig *config.Config) (provider, modelName string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int) {
+func CollectAgentMetadata(k *kit.Kit, mcpConfig *config.Config) (provider, modelName string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int) {
 	modelString := viper.GetString("model")
 	provider, modelName, _ = kit.ParseModelString(modelString)
 	if modelName == "" {
@@ -25,13 +24,9 @@ func CollectAgentMetadata(mcpAgent *agent.Agent, mcpConfig *config.Config) (prov
 		serverNames = append(serverNames, name)
 	}
 
-	for _, tool := range mcpAgent.GetTools() {
-		info := tool.Info()
-		toolNames = append(toolNames, info.Name)
-	}
-
-	mcpToolCount = mcpAgent.GetMCPToolCount()
-	extensionToolCount = mcpAgent.GetExtensionToolCount()
+	toolNames = k.GetToolNames()
+	mcpToolCount = k.GetMCPToolCount()
+	extensionToolCount = k.GetExtensionToolCount()
 
 	return provider, modelName, serverNames, toolNames, mcpToolCount, extensionToolCount
 }
@@ -46,13 +41,12 @@ func BuildAppOptions(mcpConfig *config.Config, modelName string, serverNames, to
 		StreamingEnabled: viper.GetBool("stream"),
 		Quiet:            quietFlag,
 		Debug:            viper.GetBool("debug"),
-		CompactMode:      viper.GetBool("compact"),
 	}
 }
 
 // DisplayDebugConfig builds and displays the debug configuration map through
 // the CLI for non-interactive mode.
-func DisplayDebugConfig(cli *ui.CLI, mcpAgent *agent.Agent, mcpConfig *config.Config, provider string) {
+func DisplayDebugConfig(cli *ui.CLI, k *kit.Kit, mcpConfig *config.Config, provider string) {
 	if quietFlag || cli == nil || !viper.GetBool("debug") {
 		return
 	}
@@ -89,7 +83,7 @@ func DisplayDebugConfig(cli *ui.CLI, mcpAgent *agent.Agent, mcpConfig *config.Co
 	if len(mcpConfig.MCPServers) > 0 {
 		mcpServers := make(map[string]any)
 		loadedServerSet := make(map[string]bool)
-		for _, name := range mcpAgent.GetLoadedServerNames() {
+		for _, name := range k.GetLoadedServerNames() {
 			loadedServerSet[name] = true
 		}
 
@@ -130,13 +124,12 @@ func DisplayDebugConfig(cli *ui.CLI, mcpAgent *agent.Agent, mcpConfig *config.Co
 
 // SetupCLIForNonInteractive creates the CLI display layer for non-interactive
 // mode (--prompt). Returns nil when quiet mode is active.
-func SetupCLIForNonInteractive(mcpAgent *agent.Agent) (*ui.CLI, error) {
-	agentAdapter := &agentUIAdapter{agent: mcpAgent}
+func SetupCLIForNonInteractive(k *kit.Kit) (*ui.CLI, error) {
+	agentAdapter := &kitUIAdapter{kit: k}
 	return ui.SetupCLI(&ui.CLISetupOptions{
 		Agent:          agentAdapter,
 		ModelString:    viper.GetString("model"),
 		Debug:          viper.GetBool("debug"),
-		Compact:        viper.GetBool("compact"),
 		Quiet:          quietFlag,
 		ShowDebug:      false,
 		ProviderAPIKey: viper.GetString("provider-api-key"),

cmd/skill.go

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

examples/extensions/README.md

@@ -0,0 +1,197 @@
+# Kit Extension Examples
+
+A collection of example extensions demonstrating various Kit capabilities. These can be installed individually or as a complete collection.
+
+## Installation
+
+### Install all examples
+```bash
+kit install github.com/mark3labs/kit/examples/extensions
+```
+
+### Install with interactive selection
+```bash
+kit install github.com/mark3labs/kit/examples/extensions --select
+```
+
+### Install locally in your project
+```bash
+kit install github.com/mark3labs/kit/examples/extensions --local
+```
+
+## Extension Index
+
+### Core Concepts
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `minimal.go` | Minimal viable extension | Basic `Init()` function |
+| `plan-mode.go` | Restrict agent to read-only tools | `OnBeforeAgentStart`, `SetActiveTools` |
+| `tool-logger.go` | Log all tool calls to file | `OnToolCall`, `OnToolResult` |
+| `notify.go` | Display notifications | `PrintInfo`, `PrintBlock` |
+
+### UI & Widgets
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `widget-status.go` | Persistent status widget | `SetWidget`, `RemoveWidget` |
+| `header-footer-demo.go` | Custom header/footer | `SetHeader`, `SetFooter` |
+| `overlay-demo.go` | Modal overlay dialogs | `ShowOverlay` |
+| `compact-notify.go` | Compact mode notifications | `PrintBlock` |
+| `branded-output.go` | Custom styled output | `PrintBlock` with colors |
+
+### Input & Editor
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `custom-editor-demo.go` | Custom key handling | `SetEditor`, `EditorKeyAction` |
+| `pirate.go` | Transform user input | `OnInput`, `InputResult` |
+| `interactive-shell.go` | Custom command input | Slash commands with prompts |
+| `inline-bash.go` | Execute bash inline | Input handling, `exec` |
+
+### Session & Context
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `context-inject.go` | Inject context into prompts | `OnContextPrepare` |
+| `bookmark.go` | Bookmark messages | `AppendEntry`, `GetEntries` |
+| `project-rules.go` | Project-specific rules | Session data, file reading |
+| `protected-paths.go` | Block dangerous operations | `OnToolCall` with blocking |
+| `permission-gate.go` | Confirm destructive actions | `OnToolCall` with confirmation |
+
+### Tools & Commands
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `auto-commit.go` | Auto-commit changes | Custom tool, git operations |
+| `summarize.go` | Summarize conversation | Custom tool with parameters |
+| `confirm-destructive.go` | Confirm destructive commands | `OnToolCall` blocking |
+| `lsp-diagnostics.go` | LSP integration | Complex extension, external process |
+
+### Subagents & Background Tasks
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `kit-kit.go` | Spawn Kit as subagent | Subagent spawning |
+| `subagent-test.go` | Test subagent functionality | `SpawnSubagent` |
+| `subagent-widget.go` | Widget with subagent updates | Goroutines + widgets |
+| `dev-reload.go` | Hot reload extensions | `ReloadExtensions` |
+
+### Integrations
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `kit-telegram/` | Telegram relay for remote monitoring & control | `RegisterCommand`, `OnAgentStart/End`, `SetStatus`, `SendMessage` |
+
+### Themes
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `neon-theme.go` | Register and switch custom themes | `RegisterTheme`, `SetTheme` |
+
+### Rendering
+
+| Extension | Description | Key API |
+|-----------|-------------|---------|
+| `tool-renderer-demo.go` | Custom tool output styling | `RegisterToolRenderer` |
+| `prompt-demo.go` | Interactive prompts | `PromptSelect`, `PromptConfirm` |
+
+## Extension Details
+
+### minimal.go
+The bare minimum extension showing the required structure:
+- Package `main`
+- Import `kit/ext`
+- Export `Init(api ext.API)` function
+
+### plan-mode.go
+A complete example demonstrating:
+- Slash command (`/plan`)
+- Keyboard shortcut (`ctrl+alt+p`)
+- Option registration
+- Status bar indicators
+- System prompt injection
+- Tool filtering
+
+### widget-status.go
+Shows how to create persistent UI elements:
+- Create widgets with `SetWidget`
+- Update content dynamically
+- Remove when done
+- Handle session lifecycle
+
+### context-inject.go
+Advanced context manipulation:
+- Read project files
+- Inject into LLM context
+- Filter messages
+- Use negative indices for ephemeral content
+
+### lsp-diagnostics.go
+Complex real-world example:
+- Multi-file extension
+- External process management (LSP server)
+- File watching
+- Diagnostics aggregation
+
+### kit-telegram/
+Full-featured Telegram integration:
+- Slash command with subcommands and tab completion
+- Interactive guided setup flow with prompts
+- Background long-polling goroutine
+- Progress message rendering edited in place
+- Message queue with edit-before-dispatch
+- Remote command handling from Telegram
+- Status bar and widget updates
+- Config persistence with atomic writes
+
+## Multi-File Extension Example
+
+The `kit-kit-agents/` directory demonstrates the multi-file pattern:
+
+```
+kit-kit-agents/
+├── main.go          # Entry point with Init()
+├── agent.go         # Agent configuration
+├── manager.go       # Agent lifecycle management
+└── README.md        # Documentation
+```
+
+When the repo is installed, all files in subdirectories with `main.go` are loaded as separate extensions.
+
+## Testing & Validation
+
+After installing, test the extensions:
+
+```bash
+# List all loaded extensions
+kit extensions list
+
+# Validate all extensions
+kit extensions validate
+
+# Run with a specific extension
+kit -e ~/.local/share/kit/git/github.com/mark3labs/kit/examples/extensions/plan-mode.go
+```
+
+## Creating Your Own
+
+1. Copy `minimal.go` as a starting point
+2. Modify the `Init()` function to register your handlers
+3. Use the other examples for reference on specific APIs
+4. Test with `kit -e your-extension.go`
+5. Share by pushing to a git repository!
+
+## Update
+
+To get the latest examples:
+
+```bash
+kit install github.com/mark3labs/kit/examples/extensions --update
+```
+
+## See Also
+
+- [Kit Extensions Guide](https://github.com/mark3labs/kit/blob/main/.agents/skills/kit-extensions/SKILL.md)
+- [API Reference](https://github.com/mark3labs/kit/blob/main/internal/extensions/api.go)
+- [Example Extensions Source](https://github.com/mark3labs/kit/tree/main/examples/extensions)

examples/extensions/all_extensions_load_test.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/mark3labs/kit/pkg/extensions/test"
+)
+
+// TestAllExtensions_Load is a smoke test that verifies every single-file
+// example extension in this directory can be loaded by the Yaegi interpreter
+// without errors. This catches syntax errors, missing symbols, bad imports,
+// and Init signature mismatches.
+func TestAllExtensions_Load(t *testing.T) {
+	files := extensionFiles(t)
+
+	for _, file := range files {
+		t.Run(file, func(t *testing.T) {
+			harness := test.New(t)
+			ext := harness.LoadFile(file)
+			if ext == nil {
+				t.Fatalf("%s: extension should not be nil after loading", file)
+			}
+		})
+	}
+
+	t.Logf("successfully loaded %d extensions", len(files))
+}

examples/extensions/all_extensions_sanity_test.go

@@ -0,0 +1,253 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/mark3labs/kit/internal/extensions"
+	"github.com/mark3labs/kit/pkg/extensions/test"
+)
+
+// extensionFiles returns all single-file extensions in the current directory.
+// It skips test files, the test template, and files without an Init function.
+func extensionFiles(t *testing.T) []string {
+	t.Helper()
+
+	skip := map[string]bool{
+		"extension_test_template.go": true,
+	}
+
+	entries, err := os.ReadDir(".")
+	if err != nil {
+		t.Fatalf("failed to read directory: %v", err)
+	}
+
+	var files []string
+	for _, entry := range entries {
+		name := entry.Name()
+		if entry.IsDir() || filepath.Ext(name) != ".go" {
+			continue
+		}
+		if strings.HasSuffix(name, "_test.go") || skip[name] {
+			continue
+		}
+		src, err := os.ReadFile(name)
+		if err != nil {
+			t.Fatalf("failed to read %s: %v", name, err)
+		}
+		if !strings.Contains(string(src), "func Init(") {
+			continue
+		}
+		files = append(files, name)
+	}
+
+	if len(files) == 0 {
+		t.Fatal("no extensions found — check the directory")
+	}
+	return files
+}
+
+// TestAllExtensions_Lifecycle verifies that every extension survives a full
+// SessionStart → SessionShutdown round-trip without errors.
+func TestAllExtensions_Lifecycle(t *testing.T) {
+	for _, file := range extensionFiles(t) {
+		t.Run(file, func(t *testing.T) {
+			harness := test.New(t)
+			harness.LoadFile(file)
+
+			_, err := harness.Emit(extensions.SessionStartEvent{
+				SessionID: "smoke-test-session",
+			})
+			if err != nil {
+				t.Fatalf("SessionStart error: %v", err)
+			}
+
+			_, err = harness.Emit(extensions.SessionShutdownEvent{})
+			if err != nil {
+				t.Fatalf("SessionShutdown error: %v", err)
+			}
+		})
+	}
+}
+
+// TestAllExtensions_CommandSanity checks that every registered command has
+// a non-empty name, a non-empty description, no spaces in the name, no
+// leading slash, a non-nil Execute function, and no duplicate names.
+func TestAllExtensions_CommandSanity(t *testing.T) {
+	for _, file := range extensionFiles(t) {
+		t.Run(file, func(t *testing.T) {
+			harness := test.New(t)
+			harness.LoadFile(file)
+
+			cmds := harness.RegisteredCommands()
+			seen := make(map[string]bool)
+			for _, cmd := range cmds {
+				if cmd.Name == "" {
+					t.Error("command has empty name")
+				}
+				if strings.Contains(cmd.Name, " ") {
+					t.Errorf("command %q contains spaces", cmd.Name)
+				}
+				if strings.HasPrefix(cmd.Name, "/") {
+					t.Errorf("command %q has leading slash (framework adds it)", cmd.Name)
+				}
+				if cmd.Description == "" {
+					t.Errorf("command %q has empty description", cmd.Name)
+				}
+				if cmd.Execute == nil {
+					t.Errorf("command %q has nil Execute function", cmd.Name)
+				}
+				if seen[cmd.Name] {
+					t.Errorf("duplicate command name %q", cmd.Name)
+				}
+				seen[cmd.Name] = true
+			}
+		})
+	}
+}
+
+// TestAllExtensions_ToolSanity checks that every registered tool has a
+// non-empty name, a non-empty description, at least one executor, valid
+// JSON in its Parameters field, and no duplicate names.
+func TestAllExtensions_ToolSanity(t *testing.T) {
+	for _, file := range extensionFiles(t) {
+		t.Run(file, func(t *testing.T) {
+			harness := test.New(t)
+			harness.LoadFile(file)
+
+			tools := harness.RegisteredTools()
+			seen := make(map[string]bool)
+			for _, tool := range tools {
+				if tool.Name == "" {
+					t.Error("tool has empty name")
+				}
+				if tool.Description == "" {
+					t.Errorf("tool %q has empty description", tool.Name)
+				}
+				if tool.Execute == nil && tool.ExecuteWithContext == nil {
+					t.Errorf("tool %q has no executor (both Execute and ExecuteWithContext are nil)", tool.Name)
+				}
+				if tool.Parameters != "" && !json.Valid([]byte(tool.Parameters)) {
+					t.Errorf("tool %q has invalid JSON in Parameters: %s", tool.Name, tool.Parameters)
+				}
+				if seen[tool.Name] {
+					t.Errorf("duplicate tool name %q", tool.Name)
+				}
+				seen[tool.Name] = true
+			}
+		})
+	}
+}
+
+// TestAllExtensions_ZeroValueEvents fires every event type (as zero-value
+// structs) at each extension and verifies no errors are returned. Extensions
+// should be resilient to events they don't handle and to events with empty
+// fields.
+func TestAllExtensions_ZeroValueEvents(t *testing.T) {
+	// Build the set of zero-value events for every event type.
+	zeroEvents := []extensions.Event{
+		extensions.ToolCallEvent{},
+		extensions.ToolExecutionStartEvent{},
+		extensions.ToolExecutionEndEvent{},
+		extensions.ToolOutputEvent{},
+		extensions.ToolResultEvent{},
+		extensions.InputEvent{},
+		extensions.BeforeAgentStartEvent{},
+		extensions.AgentStartEvent{},
+		extensions.AgentEndEvent{},
+		extensions.MessageStartEvent{},
+		extensions.MessageUpdateEvent{},
+		extensions.MessageEndEvent{},
+		extensions.SessionStartEvent{},
+		extensions.SessionShutdownEvent{},
+		extensions.ModelChangeEvent{},
+		extensions.ContextPrepareEvent{},
+		extensions.BeforeForkEvent{},
+		extensions.BeforeSessionSwitchEvent{},
+		extensions.BeforeCompactEvent{},
+		extensions.SubagentStartEvent{},
+		extensions.SubagentChunkEvent{},
+		extensions.SubagentEndEvent{},
+	}
+
+	for _, file := range extensionFiles(t) {
+		t.Run(file, func(t *testing.T) {
+			harness := test.New(t)
+			harness.LoadFile(file)
+
+			for _, ev := range zeroEvents {
+				_, err := harness.Emit(ev)
+				if err != nil {
+					t.Errorf("event %T returned error: %v", ev, err)
+				}
+			}
+		})
+	}
+}
+
+// TestAllExtensions_WidgetSanity emits SessionStart and then checks that
+// any widgets set during initialization have non-empty IDs and valid
+// placements.
+func TestAllExtensions_WidgetSanity(t *testing.T) {
+	validPlacements := map[extensions.WidgetPlacement]bool{
+		"above": true,
+		"below": true,
+	}
+
+	for _, file := range extensionFiles(t) {
+		t.Run(file, func(t *testing.T) {
+			harness := test.New(t)
+			harness.LoadFile(file)
+
+			// Trigger SessionStart so extensions that set widgets on init do so.
+			_, _ = harness.Emit(extensions.SessionStartEvent{
+				SessionID: "widget-sanity-test",
+			})
+
+			// Widgets is an exported field on MockContext; reads are safe
+			// here because Emit returned synchronously.
+			for id, w := range harness.Context().Widgets {
+				if w.ID == "" {
+					t.Errorf("widget stored with key %q has empty ID", id)
+				}
+				if w.ID != id {
+					t.Errorf("widget key %q doesn't match widget ID %q", id, w.ID)
+				}
+				if !validPlacements[w.Placement] {
+					t.Errorf("widget %q has invalid placement %q (want \"above\" or \"below\")", id, w.Placement)
+				}
+			}
+		})
+	}
+}
+
+// TestAllExtensions_IdempotentLifecycle verifies that receiving SessionStart
+// twice and SessionShutdown twice doesn't cause errors — extensions should
+// be defensive about repeated lifecycle events.
+func TestAllExtensions_IdempotentLifecycle(t *testing.T) {
+	for _, file := range extensionFiles(t) {
+		t.Run(file, func(t *testing.T) {
+			harness := test.New(t)
+			harness.LoadFile(file)
+
+			for i := range 2 {
+				_, err := harness.Emit(extensions.SessionStartEvent{
+					SessionID: "idempotent-test",
+				})
+				if err != nil {
+					t.Fatalf("SessionStart #%d error: %v", i+1, err)
+				}
+			}
+
+			for i := range 2 {
+				_, err := harness.Emit(extensions.SessionShutdownEvent{})
+				if err != nil {
+					t.Fatalf("SessionShutdown #%d error: %v", i+1, err)
+				}
+			}
+		})
+	}
+}

examples/extensions/auto-commit.go

@@ -0,0 +1,70 @@
+//go:build ignore
+
+package main
+
+import (
+	"os/exec"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init automatically commits staged changes when the session shuts down,
+// using the last assistant message as the commit message.
+//
+// Only commits if:
+//   - There are staged changes (git diff --cached is non-empty)
+//   - There is at least one assistant message to use as commit message
+//
+// The commit message is derived from the last assistant response, trimmed
+// to the first paragraph (max 72 chars for the subject line).
+//
+// Usage: kit -e examples/extensions/auto-commit.go
+func Init(api ext.API) {
+	api.OnSessionShutdown(func(_ ext.SessionShutdownEvent, ctx ext.Context) {
+		// Check for staged changes.
+		err := exec.Command("git", "diff", "--cached", "--quiet").Run()
+		if err == nil {
+			return // exit code 0 means no staged changes
+		}
+
+		// Get the last assistant message.
+		msgs := ctx.GetMessages()
+		var lastAssistant string
+		for i := len(msgs) - 1; i >= 0; i-- {
+			if msgs[i].Role == "assistant" {
+				lastAssistant = msgs[i].Content
+				break
+			}
+		}
+		if lastAssistant == "" {
+			return
+		}
+
+		// Build commit message: first paragraph, subject line max 72 chars.
+		subject := firstParagraph(lastAssistant)
+		if len(subject) > 72 {
+			subject = subject[:69] + "..."
+		}
+
+		// Commit.
+		cmd := exec.Command("git", "commit", "-m", subject)
+		output, err := cmd.CombinedOutput()
+		if err != nil {
+			ctx.PrintError("Auto-commit failed: " + string(output))
+			return
+		}
+		ctx.PrintInfo("Auto-committed: " + subject)
+	})
+}
+
+// firstParagraph returns the first non-empty paragraph of text.
+func firstParagraph(text string) string {
+	text = strings.TrimSpace(text)
+	// Split on double newlines (paragraph breaks).
+	parts := strings.SplitN(text, "\n\n", 2)
+	line := strings.TrimSpace(parts[0])
+	// Collapse to single line.
+	line = strings.ReplaceAll(line, "\n", " ")
+	return line
+}

examples/extensions/bookmark.go

@@ -0,0 +1,101 @@
+//go:build ignore
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	"kit/ext"
+)
+
+// Init adds bookmark commands for marking and recalling important points in
+// a conversation. Bookmarks are persisted in the session tree and survive
+// restarts.
+//
+// Commands:
+//
+//	/bookmark <label>  — bookmark the current point with a label
+//	/bookmarks         — list all bookmarks in this session
+//
+// Usage: kit -e examples/extensions/bookmark.go
+func Init(api ext.API) {
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "bookmark",
+		Description: "Bookmark the current point in the conversation",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			label := strings.TrimSpace(args)
+			if label == "" {
+				label = time.Now().Format("15:04:05")
+			}
+
+			// Count existing messages to record position.
+			msgs := ctx.GetMessages()
+
+			data, _ := json.Marshal(map[string]any{
+				"label":    label,
+				"messages": len(msgs),
+			})
+
+			_, err := ctx.AppendEntry("bookmark", string(data))
+			if err != nil {
+				ctx.PrintError("Failed to save bookmark: " + err.Error())
+				return "", nil
+			}
+
+			ctx.PrintInfo(fmt.Sprintf("Bookmarked: %s (at message %d)", label, len(msgs)))
+			return "", nil
+		},
+		Complete: func(prefix string, ctx ext.Context) []string {
+			// Suggest existing bookmark labels so the user can quickly
+			// re-bookmark at the same label.
+			entries := ctx.GetEntries("bookmark")
+			var labels []string
+			seen := map[string]bool{}
+			for _, e := range entries {
+				var data map[string]any
+				if err := json.Unmarshal([]byte(e.Data), &data); err != nil {
+					continue
+				}
+				label, _ := data["label"].(string)
+				if label == "" || seen[label] {
+					continue
+				}
+				if prefix == "" || strings.HasPrefix(strings.ToLower(label), strings.ToLower(prefix)) {
+					labels = append(labels, label)
+					seen[label] = true
+				}
+			}
+			return labels
+		},
+	})
+
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "bookmarks",
+		Description: "List all bookmarks in this session",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			entries := ctx.GetEntries("bookmark")
+			if len(entries) == 0 {
+				ctx.PrintInfo("No bookmarks yet. Use /bookmark <label> to create one.")
+				return "", nil
+			}
+
+			var lines []string
+			for i, e := range entries {
+				var data map[string]any
+				if err := json.Unmarshal([]byte(e.Data), &data); err != nil {
+					continue
+				}
+				label, _ := data["label"].(string)
+				msgCount, _ := data["messages"].(float64)
+				lines = append(lines, fmt.Sprintf("  %d. %s (msg %d, %s)",
+					i+1, label, int(msgCount), e.Timestamp[:19]))
+			}
+
+			ctx.PrintInfo("Bookmarks:\n" + strings.Join(lines, "\n"))
+			return "", nil
+		},
+	})
+}

examples/extensions/branded-output.go

@@ -0,0 +1,76 @@
+//go:build ignore
+
+// branded-output.go — Custom Message Rendering example extension for Kit.
+//
+// Demonstrates api.RegisterMessageRenderer() and ctx.RenderMessage() which
+// let extensions define reusable visual styles for output. Each renderer has
+// a name and a render function that receives content and terminal width.
+//
+// This extension registers three renderers:
+//   "success" — green-bordered block for success messages
+//   "warning" — yellow-bordered block for warnings
+//   "metric"  — compact key=value display for metrics
+//
+// Commands:
+//   /demo-render   — shows all three renderers in action
+
+package main
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	ext "kit/ext"
+)
+
+func Init(api ext.API) {
+	// Register a "success" renderer — green-accented block.
+	api.RegisterMessageRenderer(ext.MessageRendererConfig{
+		Name: "success",
+		Render: func(content string, width int) string {
+			maxW := width - 6
+			if maxW < 20 {
+				maxW = 20
+			}
+			bar := strings.Repeat("─", maxW)
+			return fmt.Sprintf("  \033[32m┌%s┐\033[0m\n  \033[32m│\033[0m \033[1;32m%s\033[0m\n  \033[32m└%s┘\033[0m",
+				bar, content, bar)
+		},
+	})
+
+	// Register a "warning" renderer — yellow-accented block.
+	api.RegisterMessageRenderer(ext.MessageRendererConfig{
+		Name: "warning",
+		Render: func(content string, width int) string {
+			maxW := width - 6
+			if maxW < 20 {
+				maxW = 20
+			}
+			bar := strings.Repeat("─", maxW)
+			return fmt.Sprintf("  \033[33m┌%s┐\033[0m\n  \033[33m│\033[0m \033[1;33m%s\033[0m\n  \033[33m└%s┘\033[0m",
+				bar, content, bar)
+		},
+	})
+
+	// Register a "metric" renderer — compact label: value format.
+	api.RegisterMessageRenderer(ext.MessageRendererConfig{
+		Name: "metric",
+		Render: func(content string, width int) string {
+			return fmt.Sprintf("  \033[36m▸\033[0m %s", content)
+		},
+	})
+
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "demo-render",
+		Description: "Demonstrate custom message renderers",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			ctx.RenderMessage("success", "All 42 tests passed in 3.2s")
+			ctx.RenderMessage("warning", "3 deprecation warnings detected")
+			ctx.RenderMessage("metric", fmt.Sprintf("build_time=%.1fs  tests=42  coverage=87%%  timestamp=%s",
+				3.2, time.Now().Format("15:04:05")))
+
+			return "Rendered three message styles.", nil
+		},
+	})
+}

examples/extensions/bridge_demo.go

@@ -0,0 +1,170 @@
+//go:build ignore
+
+// bridge_demo.go - Demonstrates the new bridged SDK APIs for extensions.
+// This extension showcases tree navigation, skill loading, template parsing,
+// and model resolution capabilities.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"kit/ext"
+)
+
+var (
+	discoveredSkills []ext.Skill
+	currentBranch    []ext.TreeNode
+)
+
+func Init(api ext.API) {
+	// Register /tree-info command to demonstrate tree navigation
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "tree-info",
+		Description: "Show current conversation tree information",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			branch := ctx.GetCurrentBranch()
+			info := fmt.Sprintf("Current branch has %d nodes:\n", len(branch))
+			for i, node := range branch {
+				info += fmt.Sprintf("  [%d] %s (%s): %s...\n", i, node.Type, node.ID[:8], truncate(node.Content, 40))
+			}
+			ctx.PrintInfo(info)
+			return "", nil
+		},
+	})
+
+	// Register /discover-skills command
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "discover-skills",
+		Description: "Discover and list available skills",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			result := ctx.DiscoverSkills()
+			if result.Error != "" {
+				return "", fmt.Errorf("discovery failed: %s", result.Error)
+			}
+			discoveredSkills = result.Skills
+
+			info := fmt.Sprintf("Discovered %d skills:\n", len(result.Skills))
+			for _, s := range result.Skills {
+				info += fmt.Sprintf("  - %s: %s\n", s.Name, s.Description)
+			}
+			ctx.PrintInfo(info)
+			return "", nil
+		},
+	})
+
+	// Register /parse-template command
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "parse-template",
+		Description: "Parse a template and show extracted variables",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			if args == "" {
+				args = "Hello {{name}}, welcome to {{place}}!"
+			}
+			tpl := ctx.ParseTemplate("demo", args)
+			info := fmt.Sprintf("Template: %s\nVariables: %v", tpl.Content, tpl.Variables)
+			ctx.PrintInfo(info)
+			return "", nil
+		},
+	})
+
+	// Register /render-template command
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "render-template",
+		Description: "Render a template with variables (usage: /render-template name=John place=Kit)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			tpl := ctx.ParseTemplate("demo", "Hello {{name}}, welcome to {{place}}!")
+			vars := ctx.ParseArguments(args, ext.ArgumentPattern{
+				Flags: map[string]string{"name": "name", "place": "place"},
+			})
+			rendered := ctx.RenderTemplate(tpl, vars.Vars)
+			ctx.PrintInfo("Rendered: " + rendered)
+			return "", nil
+		},
+	})
+
+	// Register /check-model command
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "check-model",
+		Description: "Check model capabilities and availability",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			model := args
+			if model == "" {
+				model = ctx.Model
+			}
+
+			available := ctx.CheckModelAvailable(model)
+			caps, err := ctx.GetModelCapabilities(model)
+
+			info := fmt.Sprintf("Model: %s\n", model)
+			info += fmt.Sprintf("Available: %v\n", available)
+			if err == "" {
+				info += fmt.Sprintf("Provider: %s\n", caps.Provider)
+				info += fmt.Sprintf("Context Limit: %d\n", caps.ContextLimit)
+				info += fmt.Sprintf("Reasoning: %v\n", caps.Reasoning)
+			} else {
+				info += fmt.Sprintf("Error: %s\n", err)
+			}
+			ctx.PrintInfo(info)
+			return "", nil
+		},
+	})
+
+	// Register /resolve-chain command
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "resolve-chain",
+		Description: "Resolve a model chain (usage: /resolve-chain claude-opus,gpt-4o,claude-sonnet)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			if args == "" {
+				args = "anthropic/claude-opus-4,anthropic/claude-sonnet-4,openai/gpt-4o"
+			}
+			prefs := ctx.SimpleParseArguments(args, 1)
+			chain := []string{}
+			if len(prefs) > 1 {
+				// Split the first arg by comma
+				for _, p := range strings.Split(prefs[1], ",") {
+					p = strings.TrimSpace(p)
+					if p != "" {
+						chain = append(chain, p)
+					}
+				}
+			}
+
+			result := ctx.ResolveModelChain(chain)
+			info, _ := json.MarshalIndent(result, "", "  ")
+			ctx.PrintInfo("Resolution Result:\n" + string(info))
+			return "", nil
+		},
+	})
+
+	// Register /test-conditional command
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "test-conditional",
+		Description: "Test model conditional rendering",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			content := `<if-model is="claude-*">This is for Claude models<else>This is for other models</if-model>`
+			rendered := ctx.RenderWithModelConditionals(content)
+			ctx.PrintInfo("Input: " + content)
+			ctx.PrintInfo("Output: " + rendered)
+			ctx.PrintInfo(fmt.Sprintf("Current model matches 'claude-*': %v", ctx.EvaluateModelConditional("claude-*")))
+			return "", nil
+		},
+	})
+
+	// OnSessionStart: discover skills automatically
+	api.OnSessionStart(func(e ext.SessionStartEvent, ctx ext.Context) {
+		result := ctx.DiscoverSkills()
+		if result.Error == "" && len(result.Skills) > 0 {
+			discoveredSkills = result.Skills
+			ctx.SetStatus("bridge-demo", fmt.Sprintf("%d skills", len(result.Skills)), 50)
+		}
+	})
+}
+
+func truncate(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max-3] + "..."
+}

examples/extensions/compact-notify.go

@@ -0,0 +1,56 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+
+	"kit/ext"
+)
+
+// Init registers a before-compact hook that notifies the user when
+// compaction is about to happen and optionally blocks automatic compaction.
+//
+// When automatic compaction is triggered (via --auto-compact), the extension
+// asks for user confirmation. Manual /compact commands are always allowed.
+//
+// This demonstrates the OnBeforeCompact event which allows extensions to
+// inspect context usage stats and gate the compaction process.
+//
+// Usage: kit -e examples/extensions/compact-notify.go --auto-compact
+func Init(api ext.API) {
+	api.OnBeforeCompact(func(e ext.BeforeCompactEvent, ctx ext.Context) *ext.BeforeCompactResult {
+		pct := int(e.UsagePercent * 100)
+		summary := fmt.Sprintf("Context: %dk/%dk tokens (%d%%), %d messages",
+			e.EstimatedTokens/1000, e.ContextLimit/1000, pct, e.MessageCount)
+
+		if e.IsAutomatic {
+			// Auto-compaction: ask user first.
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        "Auto-compaction triggered.\n" + summary,
+				BorderColor: "#f9e2af",
+				Subtitle:    "compact-notify",
+			})
+
+			result := ctx.PromptConfirm(ext.PromptConfirmConfig{
+				Message:      "Allow automatic compaction?",
+				DefaultValue: true,
+			})
+			if result.Cancelled || !result.Value {
+				return &ext.BeforeCompactResult{
+					Cancel: true,
+					Reason: "Auto-compaction skipped by user.",
+				}
+			}
+		} else {
+			// Manual /compact: just notify.
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        "Compacting conversation...\n" + summary,
+				BorderColor: "#89b4fa",
+				Subtitle:    "compact-notify",
+			})
+		}
+
+		return nil // allow compaction
+	})
+}

examples/extensions/confirm-destructive.go

@@ -0,0 +1,72 @@
+//go:build ignore
+
+package main
+
+import (
+	"os/exec"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init registers before-hooks for destructive session operations:
+//   - Forks: Asks for confirmation before branching to a different tree node.
+//   - New sessions: Checks for uncommitted git changes and warns before
+//     starting a new branch if the working tree is dirty.
+//
+// This demonstrates the OnBeforeFork and OnBeforeSessionSwitch events
+// which allow extensions to cancel session lifecycle operations.
+//
+// Usage: kit -e examples/extensions/confirm-destructive.go --continue
+func Init(api ext.API) {
+	// Gate /new command: warn if there are uncommitted git changes.
+	api.OnBeforeSessionSwitch(func(e ext.BeforeSessionSwitchEvent, ctx ext.Context) *ext.BeforeSessionSwitchResult {
+		if !isGitDirty() {
+			return nil // clean repo, allow switch
+		}
+
+		result := ctx.PromptConfirm(ext.PromptConfirmConfig{
+			Message: "Working tree has uncommitted changes. Start new session anyway?",
+		})
+		if result.Cancelled || !result.Value {
+			return &ext.BeforeSessionSwitchResult{
+				Cancel: true,
+				Reason: "Session switch cancelled: uncommitted git changes.",
+			}
+		}
+		return nil // user approved
+	})
+
+	// Gate fork: ask for confirmation before branching.
+	api.OnBeforeFork(func(e ext.BeforeForkEvent, ctx ext.Context) *ext.BeforeForkResult {
+		msg := "Branch to this point in the conversation?"
+		if e.IsUserMessage && e.UserText != "" {
+			// Show a preview of the user message being forked to.
+			preview := e.UserText
+			if len(preview) > 80 {
+				preview = preview[:77] + "..."
+			}
+			msg = "Fork and edit: " + preview + "\n\nContinue?"
+		}
+
+		result := ctx.PromptConfirm(ext.PromptConfirmConfig{
+			Message: msg,
+		})
+		if result.Cancelled || !result.Value {
+			return &ext.BeforeForkResult{
+				Cancel: true,
+				Reason: "Fork cancelled by user.",
+			}
+		}
+		return nil // user approved
+	})
+}
+
+// isGitDirty returns true if the git working tree has uncommitted changes.
+func isGitDirty() bool {
+	out, err := exec.Command("git", "status", "--porcelain").Output()
+	if err != nil {
+		return false // not a git repo or git not available
+	}
+	return len(strings.TrimSpace(string(out))) > 0
+}

examples/extensions/context-inject.go

@@ -0,0 +1,89 @@
+//go:build ignore
+
+// context-inject.go — Injects context from a local file into every LLM turn.
+//
+// Reads a context file (default: .kit/context.md) and prepends it as a system
+// message to every LLM context window via OnContextPrepare. This is useful for
+// injecting project-specific knowledge, coding standards, or RAG results that
+// should always be visible to the model — without cluttering the session history.
+//
+// The injected message does NOT persist in the session tree (it's ephemeral,
+// added at query time only). This means:
+//   - Changing the context file immediately affects future turns
+//   - No session bloat from repeated context injection
+//   - The model always sees the latest version of the context
+//
+// Configuration:
+//
+//	KIT_OPT_CONTEXT_FILE  — path to context file (default: .kit/context.md)
+//
+// Usage:
+//
+//	kit -e examples/extensions/context-inject.go
+//	echo "Always use error wrapping with fmt.Errorf" > .kit/context.md
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	ext "kit/ext"
+)
+
+func Init(api ext.API) {
+	api.RegisterOption(ext.OptionDef{
+		Name:        "context-file",
+		Description: "Path to the context file to inject into every turn",
+		Default:     ".kit/context.md",
+	})
+
+	api.OnContextPrepare(func(e ext.ContextPrepareEvent, ctx ext.Context) *ext.ContextPrepareResult {
+		path := ctx.GetOption("context-file")
+		if path == "" {
+			return nil
+		}
+
+		data, err := os.ReadFile(path)
+		if err != nil {
+			// File doesn't exist or can't be read — skip silently.
+			return nil
+		}
+
+		content := strings.TrimSpace(string(data))
+		if content == "" {
+			return nil
+		}
+
+		// Prepend a system message with the context file contents.
+		injected := ext.ContextMessage{
+			Index:   -1,
+			Role:    "system",
+			Content: fmt.Sprintf("[Project Context from %s]\n\n%s", path, content),
+		}
+
+		msgs := make([]ext.ContextMessage, 0, len(e.Messages)+1)
+		msgs = append(msgs, injected)
+		msgs = append(msgs, e.Messages...)
+
+		return &ext.ContextPrepareResult{Messages: msgs}
+	})
+
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "context",
+		Description: "Show or edit the injected context file path",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			path := ctx.GetOption("context-file")
+			data, err := os.ReadFile(path)
+			if err != nil {
+				return fmt.Sprintf("Context file: %s (not found or unreadable)", path), nil
+			}
+			lines := strings.Split(strings.TrimSpace(string(data)), "\n")
+			preview := strings.Join(lines, "\n")
+			if len(lines) > 10 {
+				preview = strings.Join(lines[:10], "\n") + "\n..."
+			}
+			return fmt.Sprintf("Context file: %s (%d lines)\n\n%s", path, len(lines), preview), nil
+		},
+	})
+}

examples/extensions/conversation-manager.go

@@ -0,0 +1,406 @@
+//go:build ignore
+
+// conversation-manager.go - Advanced conversation tree navigation and management.
+// This extension demonstrates:
+// - Tree navigation (GetTreeNode, GetCurrentBranch, NavigateTo)
+// - Branch summarization and collapsing
+// - Interactive tree exploration
+//
+// Commands:
+//   /tree              - Show conversation tree structure
+//   /branch            - Show current branch path
+//   /goto <entry-id>   - Navigate to a specific entry
+//   /summarize <n>     - Summarize last N messages
+//   /fresh-context     - Collapse branch and start fresh
+//   /loop <n> <prompt> - Execute prompt N times with fresh context each iteration
+
+package main
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"kit/ext"
+)
+
+var (
+	loopActive    bool
+	loopCount     int
+	loopCurrent   int
+	loopPrompt    string
+	loopStartNode string
+)
+
+func Init(api ext.API) {
+	// /tree - Show tree structure
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "tree",
+		Description: "Show conversation tree structure",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			showTree(ctx)
+			return "", nil
+		},
+	})
+
+	// /branch - Show current branch
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "branch",
+		Description: "Show current conversation branch",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			showBranch(ctx)
+			return "", nil
+		},
+	})
+
+	// /goto - Navigate to entry
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "goto",
+		Description: "Navigate to a specific entry ID (usage: /goto <entry-id>)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			if args == "" {
+				ctx.PrintError("Usage: /goto <entry-id>")
+				return "", nil
+			}
+			result := ctx.NavigateTo(args)
+			if !result.Success {
+				ctx.PrintError(fmt.Sprintf("Navigation failed: %s", result.Error))
+				return "", nil
+			}
+			ctx.PrintInfo(fmt.Sprintf("Navigated to entry: %s", args))
+
+			// Show the node we navigated to
+			node := ctx.GetTreeNode(args)
+			if node != nil {
+				ctx.PrintInfo(fmt.Sprintf("Entry type: %s, Role: %s", node.Type, node.Role))
+			}
+			return "", nil
+		},
+	})
+
+	// /summarize - Summarize recent messages
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "summarize",
+		Description: "Summarize last N messages (usage: /summarize [n=5])",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			n := 5
+			if args != "" {
+				if parsed, err := strconv.Atoi(args); err == nil && parsed > 0 {
+					n = parsed
+				}
+			}
+
+			branch := ctx.GetCurrentBranch()
+			if len(branch) < 2 {
+				ctx.PrintError("Not enough messages to summarize")
+				return "", nil
+			}
+
+			// Find range to summarize
+			startIdx := len(branch) - n - 1
+			if startIdx < 0 {
+				startIdx = 0
+			}
+			endIdx := len(branch) - 1
+
+			fromID := branch[startIdx].ID
+			toID := branch[endIdx].ID
+
+			ctx.PrintInfo(fmt.Sprintf("Summarizing messages %d to %d...", startIdx, endIdx))
+			summary := ctx.SummarizeBranch(fromID, toID)
+
+			if summary == "" {
+				ctx.PrintError("Failed to generate summary")
+				return "", nil
+			}
+
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        summary,
+				BorderColor: "#89b4fa",
+				Subtitle:    "conversation-manager · Summary",
+			})
+			return "", nil
+		},
+	})
+
+	// /fresh-context - Collapse and restart
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "fresh-context",
+		Description: "Collapse conversation to summary and start fresh",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			branch := ctx.GetCurrentBranch()
+			if len(branch) < 3 {
+				ctx.PrintError("Not enough context to collapse")
+				return "", nil
+			}
+
+			// Keep first message (system), summarize rest
+			fromID := branch[1].ID
+			toID := branch[len(branch)-1].ID
+
+			ctx.PrintInfo("Generating summary for context collapse...")
+			summary := ctx.SummarizeBranch(fromID, toID)
+
+			if summary == "" {
+				ctx.PrintError("Failed to generate summary")
+				return "", nil
+			}
+
+			// Collapse the branch
+			result := ctx.CollapseBranch(fromID, toID, summary)
+			if !result.Success {
+				ctx.PrintError(fmt.Sprintf("Collapse failed: %s", result.Error))
+				return "", nil
+			}
+
+			ctx.PrintInfo("Context collapsed. Starting fresh with summary.")
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        summary,
+				BorderColor: "#a6e3a1",
+				Subtitle:    "conversation-manager · Collapsed Context",
+			})
+
+			// Set a widget showing we're in fresh mode
+			ctx.SetWidget(ext.WidgetConfig{
+				ID:        "fresh-context",
+				Placement: ext.WidgetAbove,
+				Content:   ext.WidgetContent{Text: "🌱 Fresh Context Mode - Previous conversation collapsed"},
+				Style:     ext.WidgetStyle{BorderColor: "#a6e3a1"},
+			})
+
+			return "", nil
+		},
+	})
+
+	// /loop - Execute with fresh context each iteration
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "loop",
+		Description: "Execute prompt N times with fresh context (usage: /loop 5 analyze this code)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			if loopActive {
+				ctx.PrintError("Loop already in progress. Wait for completion.")
+				return "", nil
+			}
+
+			// Parse arguments
+			parts := strings.SplitN(args, " ", 2)
+			if len(parts) < 2 {
+				ctx.PrintError("Usage: /loop <count> <prompt>")
+				return "", nil
+			}
+
+			count, err := strconv.Atoi(parts[0])
+			if err != nil || count <= 0 || count > 10 {
+				ctx.PrintError("Invalid count (must be 1-10)")
+				return "", nil
+			}
+
+			loopCount = count
+			loopCurrent = 0
+			loopPrompt = parts[1]
+			loopActive = true
+
+			// Store current branch position
+			branch := ctx.GetCurrentBranch()
+			if len(branch) > 0 {
+				loopStartNode = branch[len(branch)-1].ID
+			}
+
+			ctx.PrintInfo(fmt.Sprintf("Starting loop: %d iterations", loopCount))
+			ctx.SetWidget(ext.WidgetConfig{
+				ID:        "loop-progress",
+				Placement: ext.WidgetAbove,
+				Content:   ext.WidgetContent{Text: fmt.Sprintf("🔄 Loop: 0/%d - %s", loopCount, loopPrompt)},
+				Style:     ext.WidgetStyle{BorderColor: "#fab387"},
+			})
+
+			// Start first iteration
+			executeLoopIteration(ctx)
+			return "", nil
+		},
+	})
+
+	// OnAgentEnd handles loop continuation
+	api.OnAgentEnd(func(e ext.AgentEndEvent, ctx ext.Context) {
+		if !loopActive {
+			return
+		}
+
+		loopCurrent++
+
+		if loopCurrent >= loopCount {
+			// Loop complete
+			loopActive = false
+			ctx.RemoveWidget("loop-progress")
+			ctx.PrintInfo(fmt.Sprintf("✅ Loop complete: %d/%d iterations", loopCurrent, loopCount))
+
+			// Show final summary
+			branch := ctx.GetCurrentBranch()
+			if len(branch) > 0 && loopStartNode != "" {
+				summary := ctx.SummarizeBranch(loopStartNode, branch[len(branch)-1].ID)
+				if summary != "" {
+					ctx.PrintBlock(ext.PrintBlockOpts{
+						Text:        summary,
+						BorderColor: "#a6e3a1",
+						Subtitle:    "conversation-manager · Loop Summary",
+					})
+				}
+			}
+			return
+		}
+
+		// Update progress
+		ctx.SetWidget(ext.WidgetConfig{
+			ID:        "loop-progress",
+			Placement: ext.WidgetAbove,
+			Content:   ext.WidgetContent{Text: fmt.Sprintf("🔄 Loop: %d/%d - %s", loopCurrent, loopCount, loopPrompt)},
+			Style:     ext.WidgetStyle{BorderColor: "#fab387"},
+		})
+
+		// Collapse previous iteration for fresh context
+		branch := ctx.GetCurrentBranch()
+		if len(branch) >= 2 {
+			// Find the user messages (look for the one before the last assistant message)
+			// We want to collapse from the user message that started this iteration
+			// to the last assistant response
+			var collapseStartIdx = -1
+			for i := len(branch) - 1; i >= 0; i-- {
+				if branch[i].Role == "assistant" {
+					// Found the last assistant message, now find the user message before it
+					for j := i - 1; j >= 0; j-- {
+						if branch[j].Role == "user" {
+							collapseStartIdx = j
+							break
+						}
+					}
+					break
+				}
+			}
+
+			if collapseStartIdx >= 0 {
+				fromID := branch[collapseStartIdx].ID
+				toID := branch[len(branch)-1].ID
+
+				ctx.PrintInfo(fmt.Sprintf("Collapsing iteration %d for fresh context...", loopCurrent))
+				summary := ctx.SummarizeBranch(fromID, toID)
+				if summary != "" {
+					result := ctx.CollapseBranch(fromID, toID, summary)
+					if result.Success {
+						ctx.PrintInfo("Context collapsed successfully")
+					} else {
+						ctx.PrintError(fmt.Sprintf("Collapse failed: %s", result.Error))
+					}
+				}
+			}
+		}
+
+		// Small delay to let UI update
+		time.Sleep(500 * time.Millisecond)
+
+		// Trigger next iteration
+		executeLoopIteration(ctx)
+	})
+}
+
+// showTree displays the conversation tree structure
+func showTree(ctx ext.Context) {
+	branch := ctx.GetCurrentBranch()
+	if len(branch) == 0 {
+		ctx.PrintInfo("Tree is empty")
+		return
+	}
+
+	var output strings.Builder
+	output.WriteString(fmt.Sprintf("Conversation Tree (%d nodes):\n\n", len(branch)))
+
+	for i, node := range branch {
+		prefix := "  "
+		if i == len(branch)-1 {
+			prefix = "▶ " // Current node
+		} else {
+			prefix = "  "
+		}
+
+		roleIcon := "💬"
+		switch node.Role {
+		case "user":
+			roleIcon = "👤"
+		case "assistant":
+			roleIcon = "🤖"
+		case "system":
+			roleIcon = "⚙️"
+		}
+
+		content := truncate(node.Content, 50)
+		if node.Type == "branch_summary" {
+			roleIcon = "📋"
+			content = "[Summary] " + truncate(node.Content, 40)
+		}
+
+		output.WriteString(fmt.Sprintf("%s%s %s: %s (%s...)\n", prefix, roleIcon, node.Role, node.ID[:8], content))
+
+		// Show children count if any
+		children := ctx.GetChildren(node.ID)
+		if len(children) > 0 {
+			output.WriteString(fmt.Sprintf("    └─ %d branch(es)\n", len(children)))
+		}
+	}
+
+	ctx.PrintBlock(ext.PrintBlockOpts{
+		Text:        output.String(),
+		BorderColor: "#89b4fa",
+		Subtitle:    "conversation-manager · Tree View",
+	})
+}
+
+// showBranch displays the current branch path
+func showBranch(ctx ext.Context) {
+	branch := ctx.GetCurrentBranch()
+	if len(branch) == 0 {
+		ctx.PrintInfo("No active branch")
+		return
+	}
+
+	var output strings.Builder
+	output.WriteString(fmt.Sprintf("Current Branch (%d nodes from root to leaf):\n\n", len(branch)))
+
+	for i, node := range branch {
+		marker := "  "
+		if i == len(branch)-1 {
+			marker = "▶ " // Current leaf
+		}
+
+		output.WriteString(fmt.Sprintf("%s[%d] %s (%s): %s\n",
+			marker, i, node.Type, node.ID[:8], truncate(node.Content, 40)))
+	}
+
+	// Show current node details
+	leaf := branch[len(branch)-1]
+	output.WriteString(fmt.Sprintf("\nCurrent Leaf:\n"))
+	output.WriteString(fmt.Sprintf("  ID: %s\n", leaf.ID))
+	output.WriteString(fmt.Sprintf("  Type: %s\n", leaf.Type))
+	output.WriteString(fmt.Sprintf("  Role: %s\n", leaf.Role))
+	output.WriteString(fmt.Sprintf("  Model: %s\n", leaf.Model))
+	output.WriteString(fmt.Sprintf("  Children: %d\n", len(leaf.Children)))
+
+	ctx.PrintBlock(ext.PrintBlockOpts{
+		Text:        output.String(),
+		BorderColor: "#cba6f7",
+		Subtitle:    "conversation-manager · Branch View",
+	})
+}
+
+// executeLoopIteration triggers the next loop iteration
+func executeLoopIteration(ctx ext.Context) {
+	iterationPrompt := fmt.Sprintf("[%d/%d] %s", loopCurrent+1, loopCount, loopPrompt)
+	ctx.SendMessage(iterationPrompt)
+}
+
+// truncate helper
+func truncate(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max-3] + "..."
+}

examples/extensions/custom-editor-demo.go

@@ -0,0 +1,137 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"kit/ext"
+)
+
+// vimActive tracks whether the vim interceptor is installed at all.
+// normalMode tracks whether we are in normal mode (true) or insert mode (false).
+var vimActive bool
+var normalMode bool
+
+// Init demonstrates the editor interceptor system. Extensions can intercept
+// key events before they reach the built-in editor and wrap the editor's
+// rendered output. This example implements a simple vim-like modal editor
+// with normal/insert mode switching.
+//
+// Slash commands:
+//   - /vim       — toggle vim mode on/off
+//   - /vim-info  — show current editor mode
+func Init(api ext.API) {
+	// /vim — toggle the vim interceptor on/off.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "vim",
+		Description: "Toggle vim-like modal editing",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			if vimActive {
+				// Turn off vim mode entirely.
+				vimActive = false
+				normalMode = false
+				ctx.ResetEditor()
+				return "Vim mode OFF. Default editor restored.", nil
+			}
+			// Turn on vim mode, start in normal mode.
+			vimActive = true
+			normalMode = true
+			ctx.SetEditor(ext.EditorConfig{
+				HandleKey: func(key string, currentText string) ext.EditorKeyAction {
+					return handleVimKey(key, currentText)
+				},
+				Render: func(width int, defaultContent string) string {
+					return renderVimMode(width, defaultContent)
+				},
+			})
+			return "Vim mode ON (NORMAL). Press 'i' to insert, Esc to return to normal, h/j/k/l to navigate.", nil
+		},
+	})
+
+	// /vim-info — show the current editor mode.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "vim-info",
+		Description: "Show current vim mode",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			if !vimActive {
+				return "Vim mode is OFF (default editor).", nil
+			}
+			if normalMode {
+				return "Vim mode ON — NORMAL mode", nil
+			}
+			return "Vim mode ON — INSERT mode (Esc to return to normal)", nil
+		},
+	})
+}
+
+// handleVimKey processes keys for both normal and insert modes.
+// The interceptor stays active in both modes so Esc can switch back.
+func handleVimKey(key string, currentText string) ext.EditorKeyAction {
+	if !normalMode {
+		// ── Insert mode: pass everything through except Esc ──
+		if key == "esc" {
+			normalMode = true
+			return ext.EditorKeyAction{Type: ext.EditorKeyConsumed}
+		}
+		return ext.EditorKeyAction{Type: ext.EditorKeyPassthrough}
+	}
+
+	// ── Normal mode ──
+	switch key {
+	// Navigation: remap hjkl to arrow keys.
+	case "h":
+		return ext.EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "left"}
+	case "j":
+		return ext.EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "down"}
+	case "k":
+		return ext.EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "up"}
+	case "l":
+		return ext.EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "right"}
+
+	// Mode switching.
+	case "i":
+		normalMode = false
+		return ext.EditorKeyAction{Type: ext.EditorKeyConsumed}
+
+	// Editing shortcuts.
+	case "x":
+		return ext.EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "delete"}
+	case "0":
+		return ext.EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "home"}
+	case "$":
+		return ext.EditorKeyAction{Type: ext.EditorKeyRemap, RemappedKey: "end"}
+
+	// Submission.
+	case "enter":
+		if strings.TrimSpace(currentText) != "" {
+			return ext.EditorKeyAction{Type: ext.EditorKeySubmit}
+		}
+		return ext.EditorKeyAction{Type: ext.EditorKeyConsumed}
+
+	// Block most printable keys in normal mode.
+	default:
+		// Let control sequences and special keys through (e.g., ctrl+c).
+		if len(key) > 1 && key != "space" {
+			return ext.EditorKeyAction{Type: ext.EditorKeyPassthrough}
+		}
+		return ext.EditorKeyAction{Type: ext.EditorKeyConsumed}
+	}
+}
+
+// renderVimMode wraps the default editor rendering with a mode indicator.
+func renderVimMode(width int, defaultContent string) string {
+	mode := "-- NORMAL --"
+	if !normalMode {
+		mode = "-- INSERT --"
+	}
+
+	indicator := fmt.Sprintf("  %s", mode)
+	padding := width - len(indicator)
+	if padding > 0 {
+		indicator += strings.Repeat(" ", padding)
+	}
+
+	return indicator + "\n" + defaultContent
+}

examples/extensions/dev-reload.go

@@ -0,0 +1,58 @@
+//go:build ignore
+
+// dev-reload.go — Extension Hot-Reload example extension for Kit.
+//
+// Demonstrates ctx.ReloadExtensions() which hot-reloads all extensions
+// from disk without restarting Kit. This is invaluable during extension
+// development: edit your extension source, then type /reload to pick up
+// changes immediately.
+//
+// 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
+
+package main
+
+import (
+	"fmt"
+	"time"
+
+	ext "kit/ext"
+)
+
+var loadedAt string
+
+func Init(api ext.API) {
+	loadedAt = time.Now().Format("15:04:05")
+
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "reload",
+		Description: "Hot-reload all extensions from disk",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			ctx.Print("Reloading extensions...")
+			err := ctx.ReloadExtensions()
+			if err != nil {
+				return "", fmt.Errorf("reload failed: %w", err)
+			}
+			return "Extensions reloaded successfully.", nil
+		},
+	})
+
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "load-time",
+		Description: "Show when this extension was loaded",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			return fmt.Sprintf("This extension was loaded at %s", loadedAt), nil
+		},
+	})
+
+	api.OnSessionStart(func(e ext.SessionStartEvent, ctx ext.Context) {
+		ctx.Print(fmt.Sprintf("[dev-reload] Extension loaded at %s", loadedAt))
+	})
+}

examples/extensions/extension_test_template.go

@@ -0,0 +1,170 @@
+// Extension Test Template
+//
+// This is a template for writing tests for your Kit extension.
+// Copy this file to your extension directory, rename it to something like
+// "my-ext_test.go", and customize it for your extension.
+//
+// Run tests with: go test -v
+//
+// IMPORTANT: This file should be in the same directory as your extension
+// and use package main, NOT package test.
+
+package main
+
+import (
+	"testing"
+
+	"github.com/mark3labs/kit/internal/extensions"
+	"github.com/mark3labs/kit/pkg/extensions/test"
+)
+
+// Test that your extension loads without errors
+func TestExtension_Loads(t *testing.T) {
+	harness := test.New(t)
+	ext := harness.LoadFile("my-ext.go") // Change to your extension filename
+
+	// Verify the extension was loaded
+	if ext == nil {
+		t.Fatal("extension should not be nil")
+	}
+}
+
+// Test your event handlers are registered
+func TestExtension_EventHandlers(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("my-ext.go")
+
+	// Uncomment the handlers your extension uses:
+	// test.AssertHasHandlers(t, harness, extensions.ToolCall)
+	// test.AssertHasHandlers(t, harness, extensions.Input)
+	// test.AssertHasHandlers(t, harness, extensions.SessionStart)
+	// test.AssertHasHandlers(t, harness, extensions.AgentEnd)
+}
+
+// Test tool registration
+func TestExtension_Tools(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("my-ext.go")
+
+	// Test that your tools are registered
+	// test.AssertToolRegistered(t, harness, "my_tool")
+
+	// Or test all registered tools
+	tools := harness.RegisteredTools()
+	t.Logf("Registered %d tools", len(tools))
+	for _, tool := range tools {
+		t.Logf("  - %s: %s", tool.Name, tool.Description)
+	}
+}
+
+// Test command registration
+func TestExtension_Commands(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("my-ext.go")
+
+	// Test that your commands are registered
+	// test.AssertCommandRegistered(t, harness, "mycommand")
+
+	// Or test all registered commands
+	cmds := harness.RegisteredCommands()
+	t.Logf("Registered %d commands", len(cmds))
+	for _, cmd := range cmds {
+		t.Logf("  - %s: %s", cmd.Name, cmd.Description)
+	}
+}
+
+// Test session start behavior
+func TestExtension_SessionStart(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("my-ext.go")
+
+	// Emit session start event
+	_, err := harness.Emit(extensions.SessionStartEvent{
+		SessionID: "test-session",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Verify expected behavior:
+	// - Did it print something?
+	// test.AssertPrinted(t, harness, "expected output")
+
+	// - Did it set a widget?
+	// test.AssertWidgetSet(t, harness, "my-widget")
+	// test.AssertWidgetText(t, harness, "my-widget", "expected text")
+
+	// - Did it set the header/footer?
+	// test.AssertHeaderSet(t, harness)
+	// test.AssertFooterSet(t, harness)
+
+	// - Did it set a status?
+	// test.AssertStatusSet(t, harness, "myext:status")
+}
+
+// Test tool call handling
+func TestExtension_ToolCall(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("my-ext.go")
+
+	// Test a specific tool call
+	result, err := harness.Emit(extensions.ToolCallEvent{
+		ToolName: "some_tool",
+		Input:    `{"key": "value"}`,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// If your extension blocks certain tools:
+	// test.AssertNotBlocked(t, result)
+	// OR
+	// test.AssertBlocked(t, result, "expected reason")
+
+	// Suppress unused variable warning (remove this when using result)
+	_ = result
+
+	// Check for print output
+	// test.AssertPrinted(t, harness, "expected message")
+}
+
+// Test input handling
+func TestExtension_InputHandling(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("my-ext.go")
+
+	// Test input that should be handled
+	result, err := harness.Emit(extensions.InputEvent{
+		Text:   "test input",
+		Source: "cli",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// If your extension handles/transforms input:
+	// test.AssertInputHandled(t, result, "handled")
+	// OR
+	// test.AssertInputTransformed(t, result, "transformed text")
+
+	// Suppress unused variable warning (remove this when using result)
+	_ = result
+}
+
+// Test with configured prompt results
+func TestExtension_WithPrompts(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("my-ext.go")
+
+	// Configure what prompts should return
+	harness.Context().SetPromptSelectResult(extensions.PromptSelectResult{
+		Value:     "option1",
+		Index:     0,
+		Cancelled: false,
+	})
+
+	// Now when your extension calls ctx.PromptSelect(), it gets the configured result
+	_, _ = harness.Emit(extensions.SessionStartEvent{SessionID: "test"})
+
+	// Verify behavior based on the selected options
+}

examples/extensions/header-footer-demo.go

@@ -0,0 +1,120 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"kit/ext"
+)
+
+// Init demonstrates the custom header/footer system. The header shows
+// project context (branch, CWD) and the footer shows a running summary
+// of agent activity. Slash commands toggle them on/off.
+func Init(api ext.API) {
+	var turnCount int
+	var lastResponse string
+
+	// Show a custom header with project context when the session starts.
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		ctx.SetHeader(ext.HeaderFooterConfig{
+			Content: ext.WidgetContent{
+				Text: fmt.Sprintf("Project: %s  |  Model: %s  |  %s",
+					ctx.CWD, ctx.Model, time.Now().Format("Jan 2, 15:04")),
+			},
+			Style: ext.WidgetStyle{
+				BorderColor: "#89b4fa",
+			},
+		})
+
+		ctx.SetFooter(ext.HeaderFooterConfig{
+			Content: ext.WidgetContent{
+				Text: "Ready  |  0 turns",
+			},
+			Style: ext.WidgetStyle{
+				BorderColor: "#a6e3a1",
+			},
+		})
+	})
+
+	// Update footer after each agent turn with activity summary.
+	api.OnAgentEnd(func(ae ext.AgentEndEvent, ctx ext.Context) {
+		turnCount++
+		lastResponse = ae.Response
+		if len(lastResponse) > 60 {
+			lastResponse = lastResponse[:57] + "..."
+		}
+
+		ctx.SetFooter(ext.HeaderFooterConfig{
+			Content: ext.WidgetContent{
+				Text: fmt.Sprintf("Turns: %d  |  Last: %s  |  %s",
+					turnCount, ae.StopReason, time.Now().Format("15:04:05")),
+			},
+			Style: ext.WidgetStyle{
+				BorderColor: "#a6e3a1",
+			},
+		})
+	})
+
+	// /header-off — remove the custom header.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "header-off",
+		Description: "Remove the custom header",
+		Execute: func(_ string, ctx ext.Context) (string, error) {
+			ctx.RemoveHeader()
+			return "Header removed.", nil
+		},
+	})
+
+	// /header-on — restore the custom header.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "header-on",
+		Description: "Restore the custom header",
+		Execute: func(_ string, ctx ext.Context) (string, error) {
+			ctx.SetHeader(ext.HeaderFooterConfig{
+				Content: ext.WidgetContent{
+					Text: fmt.Sprintf("Project: %s  |  Model: %s  |  %s",
+						ctx.CWD, ctx.Model, time.Now().Format("Jan 2, 15:04")),
+				},
+				Style: ext.WidgetStyle{
+					BorderColor: "#89b4fa",
+				},
+			})
+			return "Header restored.", nil
+		},
+	})
+
+	// /footer-off — remove the custom footer.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "footer-off",
+		Description: "Remove the custom footer",
+		Execute: func(_ string, ctx ext.Context) (string, error) {
+			ctx.RemoveFooter()
+			return "Footer removed.", nil
+		},
+	})
+
+	// /footer-on — restore the custom footer.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "footer-on",
+		Description: "Restore the custom footer",
+		Execute: func(_ string, ctx ext.Context) (string, error) {
+			ctx.SetFooter(ext.HeaderFooterConfig{
+				Content: ext.WidgetContent{
+					Text: fmt.Sprintf("Turns: %d  |  %s", turnCount, time.Now().Format("15:04:05")),
+				},
+				Style: ext.WidgetStyle{
+					BorderColor: "#a6e3a1",
+				},
+			})
+			return "Footer restored.", nil
+		},
+	})
+
+	// Clean up on shutdown.
+	api.OnSessionShutdown(func(_ ext.SessionShutdownEvent, ctx ext.Context) {
+		ctx.RemoveHeader()
+		ctx.RemoveFooter()
+	})
+}

examples/extensions/inline-bash.go

@@ -0,0 +1,52 @@
+//go:build ignore
+
+package main
+
+import (
+	"os/exec"
+	"regexp"
+	"strings"
+
+	"kit/ext"
+)
+
+// 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.
+//
+// Examples:
+//
+//	"Fix the tests on !{git branch --show-current}"
+//	  → "Fix the tests on main"
+//
+//	"The current directory is !{pwd}"
+//	  → "The current directory is /home/user/project"
+//
+// Usage: kit -e examples/extensions/inline-bash.go
+func Init(api ext.API) {
+	// Matches !{...} with non-greedy content.
+	re := regexp.MustCompile(`!\{([^}]+)\}`)
+
+	api.OnInput(func(ev ext.InputEvent, ctx ext.Context) *ext.InputResult {
+		if !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,
+		}
+	})
+}

examples/extensions/interactive-shell.go

@@ -0,0 +1,123 @@
+//go:build ignore
+
+// interactive-shell.go — TUI Suspend example extension for Kit.
+//
+// Demonstrates ctx.SuspendTUI() which temporarily releases the terminal
+// from the TUI so interactive subprocesses can run with full terminal
+// control. The TUI is automatically restored when the callback returns.
+//
+// Commands:
+//   /edit <file>   — opens $EDITOR (or vi) to edit a file
+//   /shell         — drops into an interactive shell session
+//   /run <cmd>     — runs a command with full terminal I/O (no TUI capture)
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+
+	ext "kit/ext"
+)
+
+func Init(api ext.API) {
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "edit",
+		Description: "Open $EDITOR to edit a file (TUI suspends)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			file := strings.TrimSpace(args)
+			if file == "" {
+				return "", fmt.Errorf("usage: /edit <file>")
+			}
+
+			editor := os.Getenv("EDITOR")
+			if editor == "" {
+				editor = "vi"
+			}
+
+			ctx.Print(fmt.Sprintf("Opening %s in %s...", file, editor))
+
+			err := ctx.SuspendTUI(func() {
+				cmd := exec.Command(editor, file)
+				cmd.Stdin = os.Stdin
+				cmd.Stdout = os.Stdout
+				cmd.Stderr = os.Stderr
+				cmd.Run()
+			})
+			if err != nil {
+				return "", fmt.Errorf("editor session failed: %w", err)
+			}
+
+			return fmt.Sprintf("Finished editing %s", file), nil
+		},
+		Complete: func(prefix string, ctx ext.Context) []string {
+			// Suggest files in the current directory.
+			entries, err := os.ReadDir(".")
+			if err != nil {
+				return nil
+			}
+			var results []string
+			for _, e := range entries {
+				name := e.Name()
+				if strings.HasPrefix(name, prefix) {
+					results = append(results, name)
+				}
+			}
+			return results
+		},
+	})
+
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "shell",
+		Description: "Drop into an interactive shell (TUI suspends)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			shell := os.Getenv("SHELL")
+			if shell == "" {
+				shell = "/bin/sh"
+			}
+
+			ctx.Print(fmt.Sprintf("Starting %s... (type 'exit' to return to Kit)", shell))
+
+			err := ctx.SuspendTUI(func() {
+				cmd := exec.Command(shell)
+				cmd.Stdin = os.Stdin
+				cmd.Stdout = os.Stdout
+				cmd.Stderr = os.Stderr
+				cmd.Run()
+			})
+			if err != nil {
+				return "", fmt.Errorf("shell session failed: %w", err)
+			}
+
+			return "Shell session ended, TUI restored.", nil
+		},
+	})
+
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "run",
+		Description: "Run a command with full terminal I/O (TUI suspends)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			cmdStr := strings.TrimSpace(args)
+			if cmdStr == "" {
+				return "", fmt.Errorf("usage: /run <command>")
+			}
+
+			ctx.Print(fmt.Sprintf("Running: %s", cmdStr))
+
+			err := ctx.SuspendTUI(func() {
+				cmd := exec.Command("sh", "-c", cmdStr)
+				cmd.Stdin = os.Stdin
+				cmd.Stdout = os.Stdout
+				cmd.Stderr = os.Stderr
+				cmd.Run()
+			})
+			if err != nil {
+				return "", fmt.Errorf("command failed: %w", err)
+			}
+
+			return "Command finished, TUI restored.", nil
+		},
+	})
+}

examples/extensions/kit-kit-agents/ext-expert.md

@@ -0,0 +1,36 @@
+---
+name: ext-expert
+description: Kit extensions — tools, events, commands, widgets, editor interceptors
+tools: read,grep,glob
+---
+You are an expert on Kit's extension system. Your job is to research and answer questions about how Kit extensions work.
+
+## Key Files
+
+- `internal/extensions/api.go` — Extension API surface, Context struct, all types
+- `internal/extensions/runner.go` — Event dispatch, extension registry, widget/header/footer storage
+- `internal/extensions/loader.go` — Yaegi interpreter setup, extension loading
+- `internal/extensions/symbols.go` — Yaegi symbol exports
+- `internal/extensions/events.go` — Event type definitions
+- `examples/extensions/` — Example extensions demonstrating all features
+
+## Architecture
+
+Kit extensions are Go files interpreted at runtime by Yaegi. Each extension exports `func Init(api ext.API)` and uses the API to register:
+
+- **Event handlers**: OnSessionStart, OnToolCall, OnToolResult, OnInput, OnAgentEnd, etc.
+- **Custom tools**: ToolDef with name, description, JSON Schema parameters, Execute function
+- **Slash commands**: CommandDef with name, description, Execute function (receives Context)
+- **Tool renderers**: ToolRenderConfig with custom RenderHeader/RenderBody
+- **Widgets**: ctx.SetWidget/RemoveWidget for persistent UI elements
+- **Headers/Footers**: ctx.SetHeader/SetFooter for chrome customization
+- **Editor interceptors**: ctx.SetEditor for key interception and render wrapping
+- **Prompts/Overlays**: ctx.PromptSelect/PromptConfirm/PromptInput/ShowOverlay
+
+## Critical Yaegi Limitations
+
+- All function fields in structs must be anonymous closures, NOT named function references
+- No interfaces exported to extensions — only concrete structs
+- Extensions run in isolated interpreters with stdlib + os/exec access
+
+When answering, cite specific file paths and line numbers. Provide concrete code examples.

examples/extensions/kit-kit-agents/llm-expert.md

@@ -0,0 +1,34 @@
+---
+name: llm-expert
+description: Kit LLM system — providers, streaming, agent loop, tool execution
+tools: read,grep,glob
+---
+You are an expert on Kit's LLM integration and agent system. Your job is to research and answer questions about how Kit communicates with language models and runs the agent loop.
+
+## Key Files
+
+- `internal/llm/provider.go` — Provider interface definition
+- `internal/llm/anthropic/` — Anthropic Claude provider
+- `internal/llm/openai/` — OpenAI-compatible provider (also used for Ollama)
+- `internal/llm/google/` — Google Gemini provider
+- `internal/agent/agent.go` — Agent loop: prompt -> LLM -> tool calls -> repeat
+- `internal/agent/tools.go` — Tool registry, built-in tool definitions
+- `internal/app/app.go` — App layer: RunOnce, RunOnceWithDisplay, event routing
+- `pkg/kit/kit.go` — SDK: New(), configuration, extension management
+
+## Architecture
+
+Kit supports multiple LLM providers through the `llm.Provider` interface. The model flag format is `provider/model-name` (e.g., `anthropic/claude-sonnet-4-5`).
+
+The agent loop in `internal/agent/` follows a standard ReAct pattern:
+1. Send conversation history + system prompt to LLM
+2. LLM responds with text and/or tool calls
+3. Execute tool calls (MCP servers + extension tools)
+4. Append tool results to conversation
+5. Repeat until LLM produces a final text response (no tool calls)
+
+Tool execution goes through MCP (Model Context Protocol) client-server architecture. Built-in MCP servers provide bash, file system, fetch, and todo tools.
+
+The App layer (`internal/app/`) manages the lifecycle: creating the agent, routing events to the UI or CLI renderer, handling cancellation, and coordinating with extensions.
+
+When answering, cite specific file paths and line numbers. Provide concrete code examples.

examples/extensions/kit-kit-agents/orchestrator.md

@@ -0,0 +1,27 @@
+---
+name: orchestrator
+description: Kit Kit orchestrator system prompt template
+---
+You are Kit Kit, an orchestrator agent with {{EXPERT_COUNT}} domain experts: {{EXPERT_NAMES}}.
+
+Your role is to coordinate these experts to research Kit's codebase and then synthesize their findings into working implementations.
+
+## Available Experts
+
+{{EXPERT_CATALOG}}
+
+## Workflow
+
+1. **Analyze** the user's request to identify which domains are relevant.
+2. **Query** the relevant experts IN PARALLEL using the `query_experts` tool. Ask specific, targeted questions.
+3. **Synthesize** the expert findings into a coherent understanding.
+4. **Implement** — you are the ONLY agent that writes files. Experts are read-only researchers.
+
+## Rules
+
+- ALWAYS query experts before implementing. Never guess about Kit internals.
+- Ask SPECIFIC questions: "How does SetWidget update the UI?" beats "Tell me about widgets."
+- Query MULTIPLE experts in a single tool call when the task spans domains (they run in parallel).
+- If an expert's answer is insufficient, query again with a more targeted question.
+- Cite the file paths and patterns from expert responses in your implementation.
+- When writing Kit extensions, remember the Yaegi closure wrapper pattern for all function fields.

examples/extensions/kit-kit-agents/tui-expert.md

@@ -0,0 +1,38 @@
+---
+name: tui-expert
+description: Kit TUI — Bubble Tea v2 components, rendering, theming, layout
+tools: read,grep,glob
+---
+You are an expert on Kit's terminal user interface. Your job is to research and answer questions about how Kit's TUI works.
+
+## Key Files
+
+- `internal/ui/model.go` — AppModel root component, View(), Update(), key handling, layout
+- `internal/ui/input.go` — InputComponent wrapping textarea + autocomplete
+- `internal/ui/overlay.go` — Modal overlay dialogs
+- `internal/ui/prompt.go` — Interactive prompt overlays (select, confirm, input)
+- `internal/ui/messages.go` — MessageRenderer for streaming messages
+- `internal/ui/compact_renderer.go` — CompactRenderer for compact mode
+- `internal/ui/block_renderer.go` — renderContentBlock() with functional options
+- `internal/ui/theme.go` — Catppuccin-based theming (GetTheme)
+- `internal/ui/commands.go` — ExtensionCommand type, slash command registry
+- `internal/ui/model_test.go` — Tests with stubAppController mock
+
+## Architecture
+
+Kit uses Bubble Tea v2 for the TUI. The component hierarchy:
+
+- **AppModel** — root component managing layout, key routing, and child components
+  - **InputComponent** — text area with autocomplete popup
+  - **StreamComponent** — streaming message display
+  - **TreeSelectorComponent** — session/model picker
+  - **promptOverlay** — interactive prompts (select, confirm, input)
+  - **overlayDialog** — modal overlay dialogs
+
+Layout (top to bottom): header, stream, separator, widgets-above, input, widgets-below, footer, status bar.
+
+Rendering uses lipgloss for styling with the Catppuccin Mocha color palette. Content blocks use `renderContentBlock()` with functional options for border, padding, background, and alignment.
+
+Extension widgets integrate via callback functions (getWidgets, getHeader, getFooter) that query the extension runner through the SDK layer, keeping the UI decoupled from extensions.
+
+When answering, cite specific file paths and line numbers. Provide concrete code examples.

examples/extensions/kit-kit.go

@@ -0,0 +1,870 @@
+//go:build ignore
+
+// Kit Kit — Meta-agent that builds Kit agents
+//
+// A team of domain-specific research experts operate IN PARALLEL to gather
+// documentation and patterns. The primary agent synthesizes their findings
+// and WRITES the actual files.
+//
+// Each expert runs as a separate `kit` subprocess with a domain-specific
+// system prompt. Experts are read-only researchers; the primary agent is
+// the only writer.
+//
+// Commands:
+//
+//	/experts          — list available experts and their status
+//	/experts-grid N   — set dashboard column count (default 3)
+//
+// Usage: kit -e examples/extensions/kit-kit.go
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"kit/ext"
+)
+
+// kitJSONOutput matches the JSON envelope produced by `kit --json`.
+type kitJSONOutput struct {
+	Response string `json:"response"`
+	Model    string `json:"model"`
+	Usage    *struct {
+		InputTokens  int64 `json:"input_tokens"`
+		OutputTokens int64 `json:"output_tokens"`
+	} `json:"usage,omitempty"`
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type expertDef struct {
+	Name        string
+	Description string
+	Tools       string
+	System      string // system prompt body
+	File        string
+}
+
+type expertState struct {
+	Def        expertDef
+	Status     string // "idle", "researching", "done", "error"
+	Question   string
+	Elapsed    time.Duration
+	LastLine   string
+	QueryCount int
+	mu         sync.Mutex
+}
+
+func (s *expertState) set(status, question, lastLine string, elapsed time.Duration) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if status != "" {
+		s.Status = status
+	}
+	if question != "" {
+		s.Question = question
+	}
+	if lastLine != "" {
+		s.LastLine = lastLine
+	}
+	if elapsed > 0 {
+		s.Elapsed = elapsed
+	}
+}
+
+func (s *expertState) snapshot() (string, string, string, time.Duration, int) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.Status, s.Question, s.LastLine, s.Elapsed, s.QueryCount
+}
+
+// ---------------------------------------------------------------------------
+// Package-level state
+// ---------------------------------------------------------------------------
+
+var (
+	mu        sync.Mutex
+	experts   = map[string]*expertState{}
+	gridCols  = 3
+	latestCtx ext.Context
+	hasCtx    bool
+	kitBinary string // resolved path to kit executable
+)
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func displayName(name string) string {
+	parts := strings.Split(name, "-")
+	for i, w := range parts {
+		if len(w) > 0 {
+			parts[i] = strings.ToUpper(w[:1]) + w[1:]
+		}
+	}
+	return strings.Join(parts, " ")
+}
+
+func runeWidth(s string) int {
+	return len([]rune(s))
+}
+
+func truncate(s string, max int) string {
+	runes := []rune(s)
+	if len(runes) <= max {
+		return s
+	}
+	if max < 4 {
+		return string(runes[:max])
+	}
+	return string(runes[:max-3]) + "..."
+}
+
+func pad(s string, width int) string {
+	w := runeWidth(s)
+	if w >= width {
+		return string([]rune(s)[:width])
+	}
+	return s + strings.Repeat(" ", width-w)
+}
+
+// parseAgentFile reads a .md file with YAML-like frontmatter.
+//
+//	---
+//	name: ext-expert
+//	description: Extensions documentation
+//	tools: read,grep,glob
+//	---
+//	System prompt body here ...
+func parseAgentFile(path string) *expertDef {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	text := string(raw)
+
+	// Must start with "---\n"
+	if !strings.HasPrefix(text, "---\n") {
+		return nil
+	}
+	rest := text[4:]
+	idx := strings.Index(rest, "\n---\n")
+	if idx < 0 {
+		return nil
+	}
+	frontmatter := rest[:idx]
+	body := strings.TrimSpace(rest[idx+5:])
+
+	fm := map[string]string{}
+	for _, line := range strings.Split(frontmatter, "\n") {
+		i := strings.Index(line, ":")
+		if i > 0 {
+			fm[strings.TrimSpace(line[:i])] = strings.TrimSpace(line[i+1:])
+		}
+	}
+	if fm["name"] == "" {
+		return nil
+	}
+	return &expertDef{
+		Name:        fm["name"],
+		Description: fm["description"],
+		Tools:       fm["tools"],
+		System:      body,
+		File:        path,
+	}
+}
+
+func loadExperts(cwd string) {
+	mu.Lock()
+	defer mu.Unlock()
+
+	experts = map[string]*expertState{}
+	dir := filepath.Join(cwd, ".kit", "agents", "kit-kit")
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
+			continue
+		}
+		if e.Name() == "orchestrator.md" {
+			continue
+		}
+		def := parseAgentFile(filepath.Join(dir, e.Name()))
+		if def == nil {
+			continue
+		}
+		key := strings.ToLower(def.Name)
+		experts[key] = &expertState{
+			Def:    *def,
+			Status: "idle",
+		}
+	}
+}
+
+func expertList() []*expertState {
+	mu.Lock()
+	defer mu.Unlock()
+	list := make([]*expertState, 0, len(experts))
+	for _, s := range experts {
+		list = append(list, s)
+	}
+	return list
+}
+
+func expertNames() string {
+	list := expertList()
+	names := make([]string, len(list))
+	for i, s := range list {
+		names[i] = displayName(s.Def.Name)
+	}
+	return strings.Join(names, ", ")
+}
+
+// ---------------------------------------------------------------------------
+// Widget grid rendering
+// ---------------------------------------------------------------------------
+
+func renderCard(s *expertState, w int) []string {
+	status, question, lastLine, elapsed, queryCount := s.snapshot()
+	inner := w - 2 // inside the box-drawing borders
+
+	// Name line
+	name := truncate(displayName(s.Def.Name), inner-1)
+
+	// Status line
+	var icon string
+	switch status {
+	case "idle":
+		icon = "○"
+	case "researching":
+		icon = "◉"
+	case "done":
+		icon = "✓"
+	default:
+		icon = "✗"
+	}
+	statusText := icon + " " + status
+	if status != "idle" {
+		statusText += fmt.Sprintf(" %ds", int(elapsed.Seconds()))
+	}
+	if queryCount > 0 {
+		statusText += fmt.Sprintf(" (%d)", queryCount)
+	}
+	statusText = truncate(statusText, inner-1)
+
+	// Work line (question or description)
+	work := question
+	if work == "" {
+		work = s.Def.Description
+	}
+	work = truncate(work, inner-1)
+
+	// Last output line
+	last := lastLine
+	if last == "" {
+		last = "—"
+	}
+	last = truncate(last, inner-1)
+
+	// Build card (use rune width for box-drawing alignment)
+	topBar := "─ " + name + " "
+	if runeWidth(topBar) < inner {
+		topBar += strings.Repeat("─", inner-runeWidth(topBar))
+	}
+
+	return []string{
+		"┌" + truncate(topBar, inner) + "┐",
+		"│ " + pad(statusText, inner-1) + "│",
+		"│ " + pad(work, inner-1) + "│",
+		"│ " + pad(last, inner-1) + "│",
+		"└" + strings.Repeat("─", inner) + "┘",
+	}
+}
+
+func buildGrid() string {
+	list := expertList()
+	if len(list) == 0 {
+		return "No experts found. Add agent .md files to .kit/agents/kit-kit/"
+	}
+
+	cols := gridCols
+	if cols > len(list) {
+		cols = len(list)
+	}
+
+	// Card width: aim for ~28 chars per card
+	cardWidth := 28
+	gap := 1
+
+	var lines []string
+	for i := 0; i < len(list); i += cols {
+		end := i + cols
+		if end > len(list) {
+			end = len(list)
+		}
+		row := list[i:end]
+
+		// Render each card in this row
+		cards := make([][]string, len(row))
+		maxHeight := 0
+		for j, s := range row {
+			cards[j] = renderCard(s, cardWidth)
+			if len(cards[j]) > maxHeight {
+				maxHeight = len(cards[j])
+			}
+		}
+
+		// Merge columns line by line
+		for line := 0; line < maxHeight; line++ {
+			var parts []string
+			for _, card := range cards {
+				if line < len(card) {
+					parts = append(parts, card[line])
+				} else {
+					parts = append(parts, strings.Repeat(" ", cardWidth))
+				}
+			}
+			lines = append(lines, strings.Join(parts, strings.Repeat(" ", gap)))
+		}
+	}
+	return strings.Join(lines, "\n")
+}
+
+func updateWidget() {
+	mu.Lock()
+	ctx := latestCtx
+	ok := hasCtx
+	mu.Unlock()
+	if !ok {
+		return
+	}
+	ctx.SetWidget(ext.WidgetConfig{
+		ID:        "kit-kit:grid",
+		Placement: ext.WidgetAbove,
+		Content: ext.WidgetContent{
+			Text: buildGrid(),
+		},
+		Style: ext.WidgetStyle{
+			NoBorder:    true,
+			BorderColor: "",
+		},
+		Priority: 10,
+	})
+}
+
+func updateFooter() {
+	mu.Lock()
+	ctx := latestCtx
+	ok := hasCtx
+	mu.Unlock()
+	if !ok {
+		return
+	}
+
+	list := expertList()
+	active := 0
+	done := 0
+	for _, s := range list {
+		st, _, _, _, _ := s.snapshot()
+		switch st {
+		case "researching":
+			active++
+		case "done":
+			done++
+		}
+	}
+
+	var mid string
+	if active > 0 {
+		mid = fmt.Sprintf("  ◉ %d researching", active)
+	} else if done > 0 {
+		mid = fmt.Sprintf("  ✓ %d done", done)
+	}
+
+	text := fmt.Sprintf("%s  |  Kit Kit%s", ctx.Model, mid)
+
+	ctx.SetFooter(ext.HeaderFooterConfig{
+		Content: ext.WidgetContent{Text: text},
+		Style:   ext.WidgetStyle{BorderColor: "#89b4fa"},
+	})
+}
+
+// ---------------------------------------------------------------------------
+// Kit binary resolution
+// ---------------------------------------------------------------------------
+
+func findKitBinary() string {
+	// Try the current process executable first.
+	if exe, err := os.Executable(); err == nil {
+		if _, err := os.Stat(exe); err == nil {
+			return exe
+		}
+	}
+	// Fall back to PATH lookup.
+	if p, err := exec.LookPath("kit"); err == nil {
+		return p
+	}
+	return "kit"
+}
+
+// ---------------------------------------------------------------------------
+// Expert query (subprocess)
+// ---------------------------------------------------------------------------
+
+func queryExpert(name, question string) (output string, exitCode int, elapsed time.Duration) {
+	mu.Lock()
+	state, ok := experts[strings.ToLower(name)]
+	mu.Unlock()
+	if !ok {
+		return fmt.Sprintf("Expert %q not found.", name), 1, 0
+	}
+
+	// Mark as researching.
+	state.mu.Lock()
+	if state.Status == "researching" {
+		state.mu.Unlock()
+		return fmt.Sprintf("Expert %q is already researching.", displayName(name)), 1, 0
+	}
+	state.Status = "researching"
+	state.Question = question
+	state.Elapsed = 0
+	state.LastLine = ""
+	state.QueryCount++
+	state.mu.Unlock()
+	updateWidget()
+
+	start := time.Now()
+
+	// Timer goroutine: update widget every second while researching.
+	done := make(chan struct{})
+	go func() {
+		ticker := time.NewTicker(1 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-done:
+				return
+			case <-ticker.C:
+				state.set("", "", "", time.Since(start))
+				updateWidget()
+				updateFooter()
+			}
+		}
+	}()
+
+	// Write system prompt to temp file.
+	tmpFile, err := os.CreateTemp("", "kit-kit-*.txt")
+	if err != nil {
+		close(done)
+		state.set("error", "", "temp file error: "+err.Error(), time.Since(start))
+		updateWidget()
+		updateFooter()
+		return "Error creating temp file: " + err.Error(), 1, time.Since(start)
+	}
+	defer os.Remove(tmpFile.Name())
+
+	if _, err := tmpFile.WriteString(state.Def.System); err != nil {
+		tmpFile.Close()
+		close(done)
+		state.set("error", "", "write error: "+err.Error(), time.Since(start))
+		updateWidget()
+		updateFooter()
+		return "Error writing system prompt: " + err.Error(), 1, time.Since(start)
+	}
+	tmpFile.Close()
+
+	// Build subprocess arguments. Use --json for structured output parsing.
+	// Don't pass --model; the subprocess inherits the same config/env default.
+	args := []string{
+		"--json",
+		"--no-session",
+		"--no-extensions",
+		"--system-prompt", tmpFile.Name(),
+		question,
+	}
+
+	var stdoutBuf, stderrBuf bytes.Buffer
+	cmd := exec.Command(kitBinary, args...)
+	cmd.Env = os.Environ()
+	cmd.Stdout = &stdoutBuf
+	cmd.Stderr = &stderrBuf
+
+	err = cmd.Run()
+	close(done)
+	elapsed = time.Since(start)
+
+	if err != nil {
+		// On error, prefer stderr for the error message; fall back to stdout.
+		errText := strings.TrimSpace(stderrBuf.String())
+		if errText == "" {
+			errText = strings.TrimSpace(stdoutBuf.String())
+		}
+		errLine := errText
+		if idx := strings.Index(errLine, "\n"); idx >= 0 {
+			errLine = errLine[:idx]
+		}
+		state.set("error", "", truncate(strings.TrimSpace(errLine), 80), elapsed)
+		updateWidget()
+		updateFooter()
+		code := 1
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			code = exitErr.ExitCode()
+		}
+		return errText, code, elapsed
+	}
+
+	// Parse JSON output from subprocess.
+	var parsed kitJSONOutput
+	result := strings.TrimSpace(stdoutBuf.String())
+	if err := json.Unmarshal([]byte(result), &parsed); err == nil {
+		result = parsed.Response
+	}
+	// else: fall back to raw stdout (e.g. older kit binary without --json)
+
+	// Extract last non-empty line for the card.
+	lines := strings.Split(result, "\n")
+	var lastLine string
+	for i := len(lines) - 1; i >= 0; i-- {
+		if strings.TrimSpace(lines[i]) != "" {
+			lastLine = lines[i]
+			break
+		}
+	}
+	state.set("done", "", truncate(lastLine, 60), elapsed)
+	updateWidget()
+	updateFooter()
+
+	return result, 0, elapsed
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator system prompt
+// ---------------------------------------------------------------------------
+
+func buildOrchestratorPrompt(cwd string) string {
+	orchPath := filepath.Join(cwd, ".kit", "agents", "kit-kit", "orchestrator.md")
+	raw, err := os.ReadFile(orchPath)
+	if err != nil {
+		// Fallback: generate a basic orchestrator prompt.
+		return buildDefaultOrchestratorPrompt()
+	}
+
+	text := string(raw)
+	// Strip frontmatter if present.
+	if strings.HasPrefix(text, "---\n") {
+		if idx := strings.Index(text[4:], "\n---\n"); idx >= 0 {
+			text = strings.TrimSpace(text[4+idx+5:])
+		}
+	}
+
+	list := expertList()
+	catalog := buildExpertCatalog(list)
+	names := make([]string, len(list))
+	for i, s := range list {
+		names[i] = displayName(s.Def.Name)
+	}
+
+	text = strings.ReplaceAll(text, "{{EXPERT_COUNT}}", fmt.Sprintf("%d", len(list)))
+	text = strings.ReplaceAll(text, "{{EXPERT_NAMES}}", strings.Join(names, ", "))
+	text = strings.ReplaceAll(text, "{{EXPERT_CATALOG}}", catalog)
+	return text
+}
+
+func buildExpertCatalog(list []*expertState) string {
+	var sb strings.Builder
+	for _, s := range list {
+		fmt.Fprintf(&sb, "### %s\n", displayName(s.Def.Name))
+		fmt.Fprintf(&sb, "**Query as:** `%s`\n", s.Def.Name)
+		fmt.Fprintf(&sb, "%s\n\n", s.Def.Description)
+	}
+	return sb.String()
+}
+
+func buildDefaultOrchestratorPrompt() string {
+	list := expertList()
+	names := make([]string, len(list))
+	for i, s := range list {
+		names[i] = displayName(s.Def.Name)
+	}
+	catalog := buildExpertCatalog(list)
+
+	return fmt.Sprintf(`You are Kit Kit, an orchestrator agent with %d domain experts: %s.
+
+Use the query_experts tool to consult experts IN PARALLEL before writing code.
+Always query multiple experts at once when the task spans multiple domains.
+
+## Available Experts
+
+%s
+
+## Workflow
+
+1. Analyze the user's request to identify which domains are relevant.
+2. Use query_experts to ask specific questions of the relevant experts.
+3. Synthesize the expert findings into a coherent implementation.
+4. Write the actual code/files — you are the only agent that writes.
+
+## Rules
+
+- ALWAYS query experts before implementing. Never guess.
+- Ask SPECIFIC questions. "How does X work?" is better than "Tell me about X".
+- Query multiple experts in a single call when possible (they run in parallel).
+- If an expert returns insufficient info, query again with a more specific question.
+`, len(list), strings.Join(names, ", "), catalog)
+}
+
+// ---------------------------------------------------------------------------
+// Init
+// ---------------------------------------------------------------------------
+
+func Init(api ext.API) {
+	kitBinary = findKitBinary()
+
+	// ── Session Start: load experts, show grid ──
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		mu.Lock()
+		latestCtx = ctx
+		hasCtx = true
+		mu.Unlock()
+
+		loadExperts(ctx.CWD)
+		updateWidget()
+		updateFooter()
+
+		names := expertNames()
+		n := len(expertList())
+		if n > 0 {
+			ctx.PrintInfo(fmt.Sprintf(
+				"Kit Kit loaded — %d experts: %s\n\n"+
+					"/experts          List experts and status\n"+
+					"/experts-grid N   Set grid columns (1-5)\n\n"+
+					"Ask me to build any Kit component!",
+				n, names))
+		} else {
+			ctx.PrintInfo(
+				"Kit Kit loaded — no experts found.\n\n" +
+					"Add agent .md files to .kit/agents/kit-kit/ to get started.\n" +
+					"See examples/extensions/kit-kit-agents/ for samples.")
+		}
+	})
+
+	// ── Before Agent Start: inject orchestrator system prompt ──
+	api.OnBeforeAgentStart(func(_ ext.BeforeAgentStartEvent, ctx ext.Context) *ext.BeforeAgentStartResult {
+		mu.Lock()
+		latestCtx = ctx
+		mu.Unlock()
+
+		prompt := buildOrchestratorPrompt(ctx.CWD)
+		return &ext.BeforeAgentStartResult{SystemPrompt: &prompt}
+	})
+
+	// ── Agent End: update footer ──
+	api.OnAgentEnd(func(_ ext.AgentEndEvent, ctx ext.Context) {
+		mu.Lock()
+		latestCtx = ctx
+		mu.Unlock()
+		updateFooter()
+	})
+
+	// ── Session Shutdown: cleanup ──
+	api.OnSessionShutdown(func(_ ext.SessionShutdownEvent, ctx ext.Context) {
+		ctx.RemoveWidget("kit-kit:grid")
+		ctx.RemoveFooter()
+	})
+
+	// ── Tool: query_experts ──
+	api.RegisterTool(ext.ToolDef{
+		Name: "query_experts",
+		Description: `Query one or more Kit domain experts IN PARALLEL. All experts run simultaneously as concurrent subprocesses.
+
+Pass an array of queries — each with an expert name and a specific question. All experts start at the same time and their results are returned together.
+
+Available experts are loaded from .kit/agents/kit-kit/*.md at session start. The default set includes:
+- ext-expert: Kit extensions — tools, events, commands, widgets, editor interceptors
+- tui-expert: Kit TUI — Bubble Tea v2 components, rendering, theming, layout
+- llm-expert: Kit LLM system — providers, streaming, agent loop, tool execution
+
+Ask specific questions about what you need to BUILD. Each expert will return documentation excerpts, code patterns, and implementation guidance.`,
+		Parameters: `{
+  "type": "object",
+  "properties": {
+    "queries": {
+      "type": "array",
+      "description": "Array of expert queries to run in parallel",
+      "items": {
+        "type": "object",
+        "properties": {
+          "expert": {
+            "type": "string",
+            "description": "Expert name (e.g. ext-expert, tui-expert, llm-expert)"
+          },
+          "question": {
+            "type": "string",
+            "description": "Specific question about what you need to build"
+          }
+        },
+        "required": ["expert", "question"]
+      }
+    }
+  },
+  "required": ["queries"]
+}`,
+		Execute: func(input string) (string, error) {
+			var params struct {
+				Queries []struct {
+					Expert   string `json:"expert"`
+					Question string `json:"question"`
+				} `json:"queries"`
+			}
+			if err := json.Unmarshal([]byte(input), &params); err != nil {
+				return "", fmt.Errorf("invalid parameters: %w", err)
+			}
+			if len(params.Queries) == 0 {
+				return "No queries provided.", nil
+			}
+
+			// Launch all experts in parallel.
+			type result struct {
+				Expert   string
+				Question string
+				Output   string
+				ExitCode int
+				Elapsed  time.Duration
+			}
+			results := make([]result, len(params.Queries))
+			var wg sync.WaitGroup
+
+			for i, q := range params.Queries {
+				wg.Add(1)
+				go func(idx int, expert, question string) {
+					defer wg.Done()
+					out, code, elapsed := queryExpert(expert, question)
+					results[idx] = result{
+						Expert:   expert,
+						Question: question,
+						Output:   out,
+						ExitCode: code,
+						Elapsed:  elapsed,
+					}
+				}(i, q.Expert, q.Question)
+			}
+			wg.Wait()
+
+			// Build combined response.
+			var sb strings.Builder
+			for _, r := range results {
+				icon := "✓"
+				if r.ExitCode != 0 {
+					icon = "✗"
+				}
+				fmt.Fprintf(&sb, "## [%s] %s (%ds)\n\n",
+					icon, displayName(r.Expert), int(r.Elapsed.Seconds()))
+
+				out := r.Output
+				if len(out) > 12000 {
+					out = out[:12000] + "\n\n... [truncated — ask follow-up for more]"
+				}
+				sb.WriteString(out)
+				sb.WriteString("\n\n---\n\n")
+			}
+			return sb.String(), nil
+		},
+	})
+
+	// ── Tool Renderer: query_experts ──
+	api.RegisterToolRenderer(ext.ToolRenderConfig{
+		ToolName:    "query_experts",
+		DisplayName: "Query Experts",
+		BorderColor: "#89b4fa",
+		RenderHeader: func(toolArgs string, width int) string {
+			var args struct {
+				Queries []struct {
+					Expert string `json:"expert"`
+				} `json:"queries"`
+			}
+			if err := json.Unmarshal([]byte(toolArgs), &args); err != nil {
+				return ""
+			}
+			names := make([]string, len(args.Queries))
+			for i, q := range args.Queries {
+				names[i] = displayName(q.Expert)
+			}
+			header := fmt.Sprintf("%d experts in parallel: %s",
+				len(args.Queries), strings.Join(names, ", "))
+			return truncate(header, width)
+		},
+		RenderBody: func(toolResult string, isError bool, width int) string {
+			if isError {
+				return "" // fall back to default
+			}
+			// Show compact summary: extract ## headers with status
+			var lines []string
+			for _, line := range strings.Split(toolResult, "\n") {
+				if strings.HasPrefix(line, "## [") {
+					lines = append(lines, line[3:]) // strip "## "
+				}
+			}
+			if len(lines) == 0 {
+				return ""
+			}
+			return strings.Join(lines, "  ·  ")
+		},
+	})
+
+	// ── Command: /experts ──
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "experts",
+		Description: "List available Kit Kit experts and their status",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			mu.Unlock()
+
+			list := expertList()
+			if len(list) == 0 {
+				return "No experts loaded. Add agent .md files to .kit/agents/kit-kit/", nil
+			}
+			var sb strings.Builder
+			for _, s := range list {
+				status, _, _, _, qc := s.snapshot()
+				fmt.Fprintf(&sb, "%s (%s, queries: %d): %s\n",
+					displayName(s.Def.Name), status, qc, s.Def.Description)
+			}
+			return sb.String(), nil
+		},
+	})
+
+	// ── Command: /experts-grid ──
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "experts-grid",
+		Description: "Set expert grid columns: /experts-grid <1-5>",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			mu.Unlock()
+
+			args = strings.TrimSpace(args)
+			n := 0
+			if _, err := fmt.Sscanf(args, "%d", &n); err != nil || n < 1 || n > 5 {
+				return "Usage: /experts-grid <1-5>", nil
+			}
+			mu.Lock()
+			gridCols = n
+			mu.Unlock()
+			updateWidget()
+			return fmt.Sprintf("Grid set to %d columns.", n), nil
+		},
+	})
+}

examples/extensions/kit-telegram/README.md

@@ -0,0 +1,111 @@
+# kit-telegram
+
+A Kit extension that relays all Kit agent runs to Telegram and lets approved Telegram users reply back into Kit.
+
+## What it does
+
+- Relays **all Kit runs** to one Telegram chat while connected
+- Edits one Telegram progress message in place during a run
+- Lets approved Telegram users send normal text replies back into Kit
+- Shows `Telegram Connected` or `Telegram Disconnected` in the status bar
+- Shows a small spinner animation as `⠋ Telegram Connecting` only while the relay is still connecting
+- On startup with an already validated enabled config, sends a short Telegram connection message to confirm the relay is up
+
+## Requirements
+
+- `kit` installed and working
+- A Telegram bot token from `@BotFather`
+- Either:
+  - A Telegram chat where you can message the bot, or
+  - A numeric Telegram chat id you want to enter manually
+- For group chats, one or more allowed Telegram user ids
+
+## Quickstart
+
+### 1. Install the extension
+
+```bash
+kit install github.com/mark3labs/kit/examples/extensions/kit-telegram
+```
+
+Or run directly:
+```bash
+kit -e path/to/kit-telegram/main.go
+```
+
+### 2. Start Kit and connect Telegram
+
+```bash
+kit
+```
+
+Inside Kit, run:
+
+```
+/telegram connect
+```
+
+You will be prompted for:
+
+- Bot token from `@BotFather`
+- Whether to auto-detect the chat by messaging the bot or enter the chat id manually
+- Allowed user ids when needed
+
+### 3. Verify the relay
+
+```
+/telegram test
+```
+
+Reply in Telegram with the code from the test message.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/telegram` | Human-friendly overview and subcommand list |
+| `/telegram status` | Raw deterministic relay state |
+| `/telegram test` | Verify outbound and inbound relay |
+| `/telegram toggle` | Enable or disable relay without deleting credentials |
+| `/telegram logout` | Remove saved credentials and disconnect relay |
+| `/telegram connect` | Run the setup flow again |
+| `/telegram clear` | Clear Telegram status and working messages from the TUI |
+
+## Remote commands (from Telegram)
+
+| Command | Description |
+|---------|-------------|
+| `/telegram` | Sends the overview back to Telegram |
+| `/telegram status` | Sends the deterministic state report to Telegram |
+| `/telegram test` | Sends a reply-code test message from Telegram |
+| `/telegram toggle` | Flips the enabled flag |
+| `/telegram logout yes` | Logs out (requires `yes` confirmation) |
+| `/telegram clear` | Clears the TUI footer and working messages |
+
+## Key APIs Used
+
+- `RegisterCommand` — Slash command with subcommands and tab completion
+- `OnSessionStart` / `OnSessionShutdown` — Lifecycle management
+- `OnAgentStart` / `OnAgentEnd` — Run tracking and progress rendering
+- `OnToolCall` / `OnToolResult` — Action tracking
+- `OnMessageEnd` — Capture assistant responses
+- `OnInput` — Mirror local messages to Telegram
+- `SetStatus` / `RemoveStatus` — Status bar indicators
+- `SetWidget` / `RemoveWidget` — Working message display
+- `PromptInput` / `PromptSelect` / `PromptConfirm` — Interactive setup flow
+- `SendMessage` — Inject Telegram replies as Kit prompts
+
+## Architecture
+
+Single Go file interpreted by Yaegi at runtime. Core components:
+
+- **Telegram Bot API client** — HTTP calls via `net/http` for getMe, getChat, getChatMember, getUpdates (long-polling), sendMessage, editMessageText
+- **Config persistence** — JSON file at `.kit/kit-telegram.json` with atomic writes
+- **Long-polling goroutine** — Background polling for Telegram updates with warmup poll, retry, and client-side timeouts
+- **Message queue** — In-memory FIFO queue for Telegram prompt input with edit-before-dispatch support
+- **Progress rendering** — `⏳ elapsed · step N` with action lines, edited in place
+- **Final rendering** — `✅/❌ elapsed` with response text, split into chunks for long output
+
+## Debug mode
+
+Set environment variable `KIT_TELEGRAM_DEBUG=1` to enable verbose debug logging.

examples/extensions/minimal.go

@@ -0,0 +1,71 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"math"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init demonstrates a minimal-chrome extension.
+// Hides the startup banner, status bar, separator, and input hint, replacing
+// them with a compact footer showing model name and a context usage bar:
+//
+//	claude-sonnet-4-5-20250929  [###-------] 30%  (3.9K/200K tokens)
+//
+// Usage: kit -e examples/extensions/minimal.go
+func Init(api ext.API) {
+	// updateFooter builds the footer text from current context stats.
+	updateFooter := func(ctx ext.Context) {
+		stats := ctx.GetContextStats()
+		pct := stats.UsagePercent * 100
+		if pct > 100 {
+			pct = 100
+		}
+		filled := int(math.Round(pct)) / 10
+		bar := strings.Repeat("#", filled) + strings.Repeat("-", 10-filled)
+
+		// Format token counts like the built-in status bar (e.g. "3.9K/200K").
+		fmtTokens := func(n int) string {
+			if n >= 1000 {
+				return fmt.Sprintf("%.1fK", float64(n)/1000)
+			}
+			return fmt.Sprintf("%d", n)
+		}
+
+		text := fmt.Sprintf("%s  [%s] %d%%", ctx.Model, bar, int(math.Round(pct)))
+		if stats.ContextLimit > 0 {
+			text += fmt.Sprintf("  (%s/%s tokens)",
+				fmtTokens(stats.EstimatedTokens), fmtTokens(stats.ContextLimit))
+		}
+
+		ctx.SetFooter(ext.HeaderFooterConfig{
+			Content: ext.WidgetContent{Text: text},
+			Style:   ext.WidgetStyle{BorderColor: "#585b70"},
+		})
+	}
+
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		// Strip built-in chrome for a minimal look.
+		ctx.SetUIVisibility(ext.UIVisibility{
+			HideStartupMessage: true,
+			HideStatusBar:      true,
+			HideSeparator:      true,
+			HideInputHint:      true,
+		})
+
+		updateFooter(ctx)
+	})
+
+	// Refresh after each agent turn — context usage changes here.
+	api.OnAgentEnd(func(_ ext.AgentEndEvent, ctx ext.Context) {
+		updateFooter(ctx)
+	})
+
+	api.OnSessionShutdown(func(_ ext.SessionShutdownEvent, ctx ext.Context) {
+		ctx.RemoveFooter()
+	})
+}

examples/extensions/neon-theme.go

@@ -0,0 +1,42 @@
+//go:build ignore
+
+package main
+
+import "kit/ext"
+
+// Init registers a "neon" theme and a /neon slash command to apply it.
+// Demonstrates how extensions can create and set themes programmatically.
+//
+// Usage: kit -e examples/extensions/neon-theme.go
+func Init(api ext.API) {
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		// Register a cyberpunk neon theme at startup.
+		ctx.RegisterTheme("neon", ext.ThemeColorConfig{
+			Primary:    ext.ThemeColor{Light: "#CC00FF", Dark: "#FF00FF"},
+			Secondary:  ext.ThemeColor{Light: "#0088CC", Dark: "#00FFFF"},
+			Success:    ext.ThemeColor{Light: "#00CC44", Dark: "#00FF66"},
+			Warning:    ext.ThemeColor{Light: "#CCAA00", Dark: "#FFFF00"},
+			Error:      ext.ThemeColor{Light: "#CC0033", Dark: "#FF0055"},
+			Info:       ext.ThemeColor{Light: "#0088CC", Dark: "#00CCFF"},
+			Text:       ext.ThemeColor{Light: "#111111", Dark: "#F0F0F0"},
+			Background: ext.ThemeColor{Light: "#F0F0F0", Dark: "#0A0A14"},
+			MdKeyword:  ext.ThemeColor{Light: "#CC00FF", Dark: "#FF00FF"},
+			MdString:   ext.ThemeColor{Light: "#00CC44", Dark: "#00FF66"},
+			MdComment:  ext.ThemeColor{Light: "#888888", Dark: "#555555"},
+		})
+
+		ctx.PrintInfo("Neon theme registered! Use /theme neon to activate.")
+	})
+
+	// Also register a /neon slash command as a shortcut.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "neon",
+		Description: "Switch to the neon cyberpunk theme",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			if err := ctx.SetTheme("neon"); err != nil {
+				return "", err
+			}
+			return "Neon theme activated!", nil
+		},
+	})
+}

examples/extensions/notify.go

@@ -0,0 +1,34 @@
+//go:build ignore
+
+package main
+
+import (
+	"os/exec"
+	"runtime"
+
+	"kit/ext"
+)
+
+// Init sends a desktop notification when the agent finishes responding.
+// Useful for long-running tasks — get notified without watching the terminal.
+
+// Supports: Linux (notify-send), macOS (osascript).
+//
+// Usage: kit -e examples/extensions/notify.go
+func Init(api ext.API) {
+	api.OnAgentEnd(func(_ ext.AgentEndEvent, ctx ext.Context) {
+		sendNotification("Kit", "Agent finished responding")
+	})
+}
+
+func sendNotification(title, body string) {
+	switch runtime.GOOS {
+	case "linux":
+		// Uses notify-send (libnotify) — available on most Linux desktops.
+		_ = exec.Command("notify-send", "-a", "Kit", title, body).Start()
+	case "darwin":
+		// Uses macOS built-in osascript for native notifications.
+		script := `display notification "` + body + `" with title "` + title + `"`
+		_ = exec.Command("osascript", "-e", script).Start()
+	}
+}

examples/extensions/overlay-demo.go

@@ -0,0 +1,123 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init demonstrates the overlay dialog system. Extensions can show modal
+// overlay dialogs that block until the user dismisses them or selects an
+// action. Four slash commands illustrate different overlay use cases.
+func Init(api ext.API) {
+	// /overlay-info — simple information dialog (no actions, dismissed with Enter or ESC).
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "overlay-info",
+		Description: "Show an info overlay dialog",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			content := "This is a simple informational overlay.\n\n" +
+				"Overlays are modal dialogs that appear over the TUI.\n" +
+				"They can display plain text or markdown content.\n\n" +
+				"Press Enter or ESC to dismiss."
+
+			result := ctx.ShowOverlay(ext.OverlayConfig{
+				Title:   "Information",
+				Content: ext.WidgetContent{Text: content},
+				Style:   ext.OverlayStyle{BorderColor: "#89b4fa"},
+			})
+
+			if result.Cancelled {
+				return "Info dialog cancelled.", nil
+			}
+			return "Info dialog dismissed.", nil
+		},
+	})
+
+	// /overlay-actions — overlay with action buttons.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "overlay-actions",
+		Description: "Show an overlay with action buttons",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			result := ctx.ShowOverlay(ext.OverlayConfig{
+				Title: "Deploy to Production?",
+				Content: ext.WidgetContent{
+					Text: "You are about to deploy the following changes:\n\n" +
+						"  - Updated API handlers (3 files)\n" +
+						"  - New database migration (v42)\n" +
+						"  - Config change: increased rate limit\n\n" +
+						"All tests are passing. Last deploy: 2 hours ago.",
+				},
+				Style:   ext.OverlayStyle{BorderColor: "#f38ba8"},
+				Width:   65,
+				Actions: []string{"Deploy", "Cancel", "Show Diff"},
+			})
+
+			if result.Cancelled {
+				return "Deployment cancelled (ESC).", nil
+			}
+			return fmt.Sprintf("Selected action: %q (index %d)", result.Action, result.Index), nil
+		},
+	})
+
+	// /overlay-markdown — overlay with markdown content.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "overlay-md",
+		Description: "Show an overlay with markdown content",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			md := "## Build Report\n\n" +
+				"| Component | Status | Duration |\n" +
+				"|-----------|--------|----------|\n" +
+				"| Frontend  | Pass   | 12.3s    |\n" +
+				"| Backend   | Pass   | 8.7s     |\n" +
+				"| E2E Tests | Pass   | 45.1s    |\n\n" +
+				"**Total time:** 66.1s\n\n" +
+				"All checks passed. Ready to merge."
+
+			result := ctx.ShowOverlay(ext.OverlayConfig{
+				Title:   "Build Report",
+				Content: ext.WidgetContent{Text: md, Markdown: true},
+				Style:   ext.OverlayStyle{BorderColor: "#a6e3a1"},
+				Width:   70,
+				Actions: []string{"Merge", "Close"},
+			})
+
+			if result.Cancelled {
+				return "Build report closed.", nil
+			}
+			return fmt.Sprintf("Build report action: %q", result.Action), nil
+		},
+	})
+
+	// /overlay-scroll — overlay with long scrollable content.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "overlay-scroll",
+		Description: "Show an overlay with scrollable content",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			var lines []string
+			lines = append(lines, "This overlay has a lot of content to demonstrate scrolling.")
+			lines = append(lines, "Use j/k or arrow keys to scroll through the content.")
+			lines = append(lines, "")
+			for i := 1; i <= 50; i++ {
+				lines = append(lines, fmt.Sprintf("  Line %02d: The quick brown fox jumps over the lazy dog.", i))
+			}
+			lines = append(lines, "")
+			lines = append(lines, "End of content. Press Enter to dismiss or ESC to cancel.")
+
+			result := ctx.ShowOverlay(ext.OverlayConfig{
+				Title:     "Log Output (50 lines)",
+				Content:   ext.WidgetContent{Text: strings.Join(lines, "\n")},
+				Style:     ext.OverlayStyle{BorderColor: "#fab387"},
+				MaxHeight: 20,
+				Actions:   []string{"OK", "Copy to Clipboard"},
+			})
+
+			if result.Cancelled {
+				return "Log viewer cancelled.", nil
+			}
+			return fmt.Sprintf("Log viewer action: %q", result.Action), nil
+		},
+	})
+}

examples/extensions/permission-gate.go

@@ -0,0 +1,64 @@
+//go:build ignore
+
+package main
+
+import (
+	"encoding/json"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init intercepts potentially dangerous bash commands and asks the user for
+// confirmation before allowing execution.
+//
+// Dangerous patterns: rm -rf, sudo, chmod 777, mkfs, dd, > /dev/
+//
+// Usage: kit -e examples/extensions/permission-gate.go
+func Init(api ext.API) {
+	// Patterns that require user confirmation.
+	dangerousPatterns := []string{
+		"rm -rf",
+		"rm -r /",
+		"sudo ",
+		"chmod 777",
+		"chmod -R 777",
+		"mkfs",
+		"dd if=",
+		"> /dev/",
+		":(){ :|:& };:",
+	}
+
+	api.OnToolCall(func(tc ext.ToolCallEvent, ctx ext.Context) *ext.ToolCallResult {
+		if tc.ToolName != "Bash" {
+			return nil
+		}
+
+		// Extract the command from the tool input JSON.
+		var input struct {
+			Command string `json:"command"`
+		}
+		if err := json.Unmarshal([]byte(tc.Input), &input); err != nil {
+			return nil
+		}
+		cmd := strings.ToLower(input.Command)
+
+		// Check for dangerous patterns.
+		for _, pattern := range dangerousPatterns {
+			if strings.Contains(cmd, strings.ToLower(pattern)) {
+				result := ctx.PromptConfirm(ext.PromptConfirmConfig{
+					Message: "Dangerous command detected: " + input.Command + "\n\nAllow execution?",
+				})
+				if result.Cancelled || !result.Value {
+					return &ext.ToolCallResult{
+						Block:  true,
+						Reason: "User denied execution of dangerous command: " + input.Command,
+					}
+				}
+				return nil // user approved
+			}
+		}
+
+		return nil
+	})
+}

examples/extensions/pirate.go

@@ -0,0 +1,28 @@
+//go:build ignore
+
+package main
+
+import "kit/ext"
+
+// Init injects a pirate persona into the system prompt, causing the LLM to
+// respond in pirate-speak. Demonstrates OnBeforeAgentStart system prompt
+// injection.
+//
+// Usage: kit -e examples/extensions/pirate.go
+func Init(api ext.API) {
+	piratePrompt := `
+You are a pirate! You must:
+- Start every response with "Ahoy!"
+- Use pirate slang (ye, matey, arr, landlubber, etc.)
+- Refer to files as "scrolls" and directories as "treasure chests"
+- Call errors "cursed mishaps" and bugs "sea monsters"
+- End responses with a pirate saying
+
+Despite the pirate persona, your technical advice must remain accurate and helpful.`
+
+	api.OnBeforeAgentStart(func(_ ext.BeforeAgentStartEvent, ctx ext.Context) *ext.BeforeAgentStartResult {
+		return &ext.BeforeAgentStartResult{
+			SystemPrompt: &piratePrompt,
+		}
+	})
+}

examples/extensions/plan-mode.go

@@ -0,0 +1,96 @@
+//go:build ignore
+
+package main
+
+import (
+	"strings"
+
+	"kit/ext"
+)
+
+// Init implements a plan/explore mode that restricts the agent to read-only
+// tools. Toggle with /plan (or start in plan mode via KIT_OPT_PLAN=true).
+
+// In plan mode the agent can only use read, grep, find, and ls — it cannot
+// write files, run bash, or make edits. This is useful for exploring a
+// codebase, reviewing architecture, or generating plans before executing.
+//
+// The status bar shows the current mode and the system prompt is augmented
+// with planning instructions when active.
+//
+// Usage: kit -e examples/extensions/plan-mode.go
+//
+// Start in plan mode: KIT_OPT_PLAN=true kit -e examples/extensions/plan-mode.go
+func Init(api ext.API) {
+	// Read-only tool set (matches core.ReadOnlyTools).
+	readOnlyTools := []string{"read", "grep", "find", "ls"}
+
+	var planActive bool
+
+	// Register "plan" option so users can start in plan mode via env/config.
+	api.RegisterOption(ext.OptionDef{
+		Name:        "plan",
+		Description: "Start in plan mode (read-only tools)",
+		Default:     "false",
+	})
+
+	// ctrl+alt+p — global shortcut to toggle plan mode.
+	api.RegisterShortcut(ext.ShortcutDef{
+		Key:         "ctrl+alt+p",
+		Description: "Toggle plan/explore mode",
+	}, func(ctx ext.Context) {
+		planActive = !planActive
+		applyMode(ctx, planActive, readOnlyTools)
+	})
+
+	// /plan — toggle plan mode on or off.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "plan",
+		Description: "Toggle plan/explore mode (ctrl+alt+p)",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			planActive = !planActive
+			applyMode(ctx, planActive, readOnlyTools)
+			return "", nil
+		},
+	})
+
+	// Check option at session start to enable plan mode from env/config.
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		opt := strings.ToLower(ctx.GetOption("plan"))
+		if opt == "true" || opt == "1" || opt == "yes" {
+			planActive = true
+			applyMode(ctx, true, readOnlyTools)
+		}
+	})
+
+	// Inject planning instructions into the system prompt when active.
+	api.OnBeforeAgentStart(func(_ ext.BeforeAgentStartEvent, ctx ext.Context) *ext.BeforeAgentStartResult {
+		if !planActive {
+			return nil
+		}
+		prompt := `You are in PLAN MODE (read-only exploration).
+You can ONLY read, search, and explore the codebase. You CANNOT write files,
+run commands, or make edits. Focus on:
+- Understanding the codebase structure and architecture
+- Identifying relevant files and patterns
+- Generating detailed plans and recommendations
+- Answering questions about how the code works
+
+When the user is ready to execute, they will exit plan mode with /plan.`
+		return &ext.BeforeAgentStartResult{
+			SystemPrompt: &prompt,
+		}
+	})
+}
+
+func applyMode(ctx ext.Context, active bool, readOnlyTools []string) {
+	if active {
+		ctx.SetActiveTools(readOnlyTools)
+		ctx.SetStatus("plan-mode", "PLAN MODE (read-only)", 10)
+		ctx.PrintInfo("Plan mode ON — agent restricted to read-only tools (read, grep, find, ls).\nUse /plan to toggle off.")
+	} else {
+		ctx.SetActiveTools(nil) // re-enable all tools
+		ctx.RemoveStatus("plan-mode")
+		ctx.PrintInfo("Plan mode OFF — all tools re-enabled.")
+	}
+}

examples/extensions/project-rules.go

@@ -0,0 +1,71 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init loads project-specific rules from .kit/rules/ into the system prompt.
+// Each .md file in the rules directory is injected as additional context,
+// giving projects a way to customise LLM behaviour without editing the
+// main system prompt.
+//
+// Place rule files in:
+//
+//	.kit/rules/code-style.md
+//	.kit/rules/testing.md
+//	.kit/rules/security.md
+//
+// Usage: kit -e examples/extensions/project-rules.go
+func Init(api ext.API) {
+	var rules string
+
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		rulesDir := filepath.Join(ctx.CWD, ".kit", "rules")
+		entries, err := os.ReadDir(rulesDir)
+		if err != nil {
+			return // no rules directory, nothing to do
+		}
+
+		var parts []string
+		for _, entry := range entries {
+			if entry.IsDir() {
+				continue
+			}
+			name := entry.Name()
+			if !strings.HasSuffix(name, ".md") && !strings.HasSuffix(name, ".txt") {
+				continue
+			}
+			data, err := os.ReadFile(filepath.Join(rulesDir, name))
+			if err != nil {
+				continue
+			}
+			content := strings.TrimSpace(string(data))
+			if content != "" {
+				parts = append(parts, "## "+strings.TrimSuffix(name, filepath.Ext(name))+"\n\n"+content)
+			}
+		}
+
+		if len(parts) == 0 {
+			return
+		}
+
+		rules = "# Project Rules\n\n" + strings.Join(parts, "\n\n---\n\n")
+		ctx.PrintInfo(fmt.Sprintf("[project-rules] Loaded %d rule file(s) from .kit/rules/", len(parts)))
+	})
+
+	api.OnBeforeAgentStart(func(_ ext.BeforeAgentStartEvent, ctx ext.Context) *ext.BeforeAgentStartResult {
+		if rules == "" {
+			return nil
+		}
+		return &ext.BeforeAgentStartResult{
+			SystemPrompt: &rules,
+		}
+	})
+}

examples/extensions/prompt-demo.go

@@ -0,0 +1,113 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init demonstrates the interactive prompt system. It registers three slash
+// commands that show each prompt type (select, confirm, input), plus a
+// combined workflow command that chains prompts together.
+func Init(api ext.API) {
+
+	// /demo-select — shows a selection list.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "demo-select",
+		Description: "Demo: pick from a list",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			result := ctx.PromptSelect(ext.PromptSelectConfig{
+				Message: "Choose your deployment target:",
+				Options: []string{"local", "staging", "production"},
+			})
+			if result.Cancelled {
+				return "Selection cancelled.", nil
+			}
+			return fmt.Sprintf("Selected: %s (index %d)", result.Value, result.Index), nil
+		},
+	})
+
+	// /demo-confirm — shows a yes/no confirmation.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "demo-confirm",
+		Description: "Demo: yes/no confirmation",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			result := ctx.PromptConfirm(ext.PromptConfirmConfig{
+				Message:      "Are you sure you want to deploy?",
+				DefaultValue: false,
+			})
+			if result.Cancelled {
+				return "Confirmation cancelled.", nil
+			}
+			if result.Value {
+				return "Confirmed! Deploying...", nil
+			}
+			return "Declined. Deployment aborted.", nil
+		},
+	})
+
+	// /demo-input — shows a text input.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "demo-input",
+		Description: "Demo: free-form text input",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			result := ctx.PromptInput(ext.PromptInputConfig{
+				Message:     "Enter the release tag:",
+				Placeholder: "v1.0.0",
+			})
+			if result.Cancelled {
+				return "Input cancelled.", nil
+			}
+			return fmt.Sprintf("Release tag: %s", result.Value), nil
+		},
+	})
+
+	// /demo-workflow — chains multiple prompts into a workflow.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "demo-workflow",
+		Description: "Demo: chained prompt workflow",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			// Step 1: select environment
+			env := ctx.PromptSelect(ext.PromptSelectConfig{
+				Message: "Step 1/3: Select environment:",
+				Options: []string{"development", "staging", "production"},
+			})
+			if env.Cancelled {
+				return "Workflow cancelled at step 1.", nil
+			}
+
+			// Step 2: enter version tag
+			tag := ctx.PromptInput(ext.PromptInputConfig{
+				Message:     "Step 2/3: Enter the version tag:",
+				Placeholder: "v1.0.0",
+			})
+			if tag.Cancelled {
+				return "Workflow cancelled at step 2.", nil
+			}
+
+			// Step 3: confirm
+			confirm := ctx.PromptConfirm(ext.PromptConfirmConfig{
+				Message: fmt.Sprintf(
+					"Step 3/3: Deploy %s to %s?",
+					tag.Value, env.Value),
+				DefaultValue: false,
+			})
+			if confirm.Cancelled {
+				return "Workflow cancelled at step 3.", nil
+			}
+			if !confirm.Value {
+				return "Deployment declined.", nil
+			}
+
+			var summary strings.Builder
+			summary.WriteString("Deployment summary:\n")
+			fmt.Fprintf(&summary, "  Environment: %s\n", env.Value)
+			fmt.Fprintf(&summary, "  Version:     %s\n", tag.Value)
+			summary.WriteString("  Status:      initiated")
+			return summary.String(), nil
+		},
+	})
+}

examples/extensions/prompt-templates.go

@@ -0,0 +1,269 @@
+//go:build ignore
+
+// prompt-templates.go - Frontmatter-driven prompt templates with model switching.
+// This extension demonstrates the new bridged SDK APIs:
+// - Tree navigation for conversation management
+// - Template parsing with {{variable}} substitution
+// - Model resolution with fallback chains
+// - Skill injection
+//
+// Usage:
+//   1. Create ~/.config/kit/prompts/debug.md with frontmatter:
+//      ---
+//      description: Debug Python code
+//      model: claude-sonnet-4-20250514
+//      skill: python
+//      ---
+//      Help me debug this Python code: {{input}}
+//
+//   2. In Kit: /debug my_script.py
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"kit/ext"
+)
+
+// PromptTemplate represents a loaded template with frontmatter
+type PromptTemplate struct {
+	Name        string
+	Description string
+	Model       string
+	Skill       string
+	Content     string
+	Variables   []string
+	Path        string
+}
+
+var (
+	templates   = make(map[string]PromptTemplate)
+	templateDir string
+)
+
+func Init(api ext.API) {
+	// Determine template directory
+	home, _ := os.UserHomeDir()
+	templateDir = filepath.Join(home, ".config", "kit", "prompts")
+
+	// Ensure directory exists
+	os.MkdirAll(templateDir, 0755)
+
+	// Register commands
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "reload-templates",
+		Description: "Reload prompt templates from disk",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			loadTemplates(ctx)
+			ctx.PrintInfo(fmt.Sprintf("Loaded %d templates from %s", len(templates), templateDir))
+			return "", nil
+		},
+	})
+
+	// Dynamic template commands are registered after loading
+	api.OnSessionStart(func(e ext.SessionStartEvent, ctx ext.Context) {
+		loadTemplates(ctx)
+		registerTemplateCommands(api, ctx)
+	})
+}
+
+// loadTemplates discovers and loads all template files
+func loadTemplates(ctx ext.Context) {
+	templates = make(map[string]PromptTemplate)
+
+	entries, err := os.ReadDir(templateDir)
+	if err != nil {
+		return
+	}
+
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".md") {
+			continue
+		}
+
+		path := filepath.Join(templateDir, entry.Name())
+		tpl, err := loadTemplateFile(path)
+		if err != nil {
+			continue
+		}
+
+		name := strings.TrimSuffix(entry.Name(), ".md")
+		templates[name] = tpl
+	}
+}
+
+// loadTemplateFile parses a template with YAML frontmatter
+func loadTemplateFile(path string) (PromptTemplate, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return PromptTemplate{}, err
+	}
+
+	content := string(data)
+	tpl := PromptTemplate{Path: path}
+
+	// Parse frontmatter
+	if strings.HasPrefix(content, "---") {
+		parts := strings.SplitN(content[3:], "---", 2)
+		if len(parts) == 2 {
+			frontmatter := strings.TrimSpace(parts[0])
+			body := strings.TrimSpace(parts[1])
+
+			// Simple line-by-line frontmatter parsing
+			for _, line := range strings.Split(frontmatter, "\n") {
+				line = strings.TrimSpace(line)
+				if line == "" || strings.HasPrefix(line, "#") {
+					continue
+				}
+
+				key, value, found := strings.Cut(line, ":")
+				if found {
+					key = strings.TrimSpace(key)
+					value = strings.TrimSpace(value)
+					switch key {
+					case "description":
+						tpl.Description = value
+					case "model":
+						tpl.Model = value
+					case "skill":
+						tpl.Skill = value
+					}
+				}
+			}
+			tpl.Content = body
+		} else {
+			tpl.Content = content
+		}
+	} else {
+		tpl.Content = content
+	}
+
+	// Parse {{variables}} using simple string parsing
+	// (Can't use ctx.ParseTemplate here since we're in Init, not a handler)
+	var vars []string
+	for {
+		start := strings.Index(tpl.Content, "{{")
+		if start == -1 {
+			break
+		}
+		end := strings.Index(tpl.Content[start:], "}}")
+		if end == -1 {
+			break
+		}
+		varName := strings.TrimSpace(tpl.Content[start+2 : start+end])
+		vars = append(vars, varName)
+		tpl.Content = tpl.Content[:start] + "{{" + varName + "}}" + tpl.Content[start+end+2:]
+	}
+	tpl.Variables = vars
+
+	return tpl, nil
+}
+
+// registerTemplateCommands dynamically registers commands for each template
+func registerTemplateCommands(api ext.API, ctx ext.Context) {
+	for name, tpl := range templates {
+		// Skip if already registered (we'd need to track this)
+		tplCopy := tpl // Capture for closure
+		nameCopy := name
+
+		// Build description with metadata
+		desc := tplCopy.Description
+		if desc == "" {
+			desc = fmt.Sprintf("Run %s template", nameCopy)
+		}
+		if tplCopy.Model != "" {
+			desc += fmt.Sprintf(" [%s", tplCopy.Model)
+			if tplCopy.Skill != "" {
+				desc += fmt.Sprintf(" +%s", tplCopy.Skill)
+			}
+			desc += "]"
+		}
+
+		api.RegisterCommand(ext.CommandDef{
+			Name:        nameCopy,
+			Description: desc,
+			Execute: func(args string, ctx ext.Context) (string, error) {
+				return executeTemplate(ctx, tplCopy, args)
+			},
+		})
+	}
+}
+
+// executeTemplate runs a template with the given arguments
+func executeTemplate(ctx ext.Context, tpl PromptTemplate, args string) (string, error) {
+	// Store original model for restoration
+	originalModel := ctx.Model
+
+	// 1. Resolve and switch model if specified
+	if tpl.Model != "" {
+		// Parse model chain (comma-separated)
+		preferences := strings.Split(tpl.Model, ",")
+		for i := range preferences {
+			preferences[i] = strings.TrimSpace(preferences[i])
+		}
+
+		result := ctx.ResolveModelChain(preferences)
+		if result.Error != "" {
+			ctx.PrintError(fmt.Sprintf("Model resolution failed: %s", result.Error))
+			// Continue with current model
+		} else {
+			ctx.PrintInfo(fmt.Sprintf("Switching to model: %s", result.Model))
+			if err := ctx.SetModel(result.Model); err != nil {
+				ctx.PrintError(fmt.Sprintf("Failed to switch model: %s", err.Error()))
+			}
+		}
+	}
+
+	// 2. Inject skill if specified
+	if tpl.Skill != "" {
+		err := ctx.InjectSkillAsContext(tpl.Skill)
+		if err != "" {
+			ctx.PrintError(fmt.Sprintf("Skill injection failed: %s", err))
+		} else {
+			ctx.PrintInfo(fmt.Sprintf("Injected skill: %s", tpl.Skill))
+		}
+	}
+
+	// 3. Parse and render template
+	parsed := ctx.ParseTemplate(tpl.Name, tpl.Content)
+
+	// Build variable map
+	vars := make(map[string]string)
+
+	// Simple argument parsing: first arg is $1 (input), rest is $@
+	if len(parsed.Variables) > 0 {
+		argsList := ctx.SimpleParseArguments(args, len(parsed.Variables))
+		for i, varName := range parsed.Variables {
+			if i < len(parsed.Variables) && i+1 < len(argsList) {
+				vars[varName] = argsList[i+1]
+			}
+		}
+		// If single variable, use full args
+		if len(parsed.Variables) == 1 && vars[parsed.Variables[0]] == "" {
+			vars[parsed.Variables[0]] = args
+		}
+	}
+
+	// Render with model conditionals
+	content := ctx.RenderWithModelConditionals(tpl.Content)
+	rendered := ctx.RenderTemplate(ext.PromptTemplate{Name: tpl.Name, Content: content, Variables: parsed.Variables}, vars)
+
+	// 4. Send the rendered prompt
+	ctx.SendMessage(rendered)
+
+	// 5. Schedule model restoration after turn completes
+	// We use a goroutine to wait and restore
+	if tpl.Model != "" && originalModel != "" {
+		go func() {
+			// Note: In a real implementation, we'd use OnAgentEnd event
+			// For now, the user can manually switch back
+			ctx.SetStatus("template-mode", fmt.Sprintf("Template: %s (model will restore)", tpl.Name), 20)
+		}()
+	}
+
+	return fmt.Sprintf("Executing template: %s", tpl.Name), nil
+}

examples/extensions/protected-paths.go

@@ -0,0 +1,114 @@
+//go:build ignore
+
+package main
+
+import (
+	"encoding/json"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init blocks tool calls that attempt to write, edit, or delete files in
+// protected paths.
+//
+// Protected: .env*, .git/, secrets/, credentials*, *.pem, *.key
+//
+// Usage: kit -e examples/extensions/protected-paths.go
+func Init(api ext.API) {
+	// Tools that modify files.
+	writeTools := map[string]bool{
+		"Write": true,
+		"Edit":  true,
+		"Bash":  true,
+	}
+
+	// Path patterns to protect (checked against the file_path / filePath field).
+	protectedPatterns := []string{
+		".env",
+		".git/",
+		"secrets/",
+		"credentials",
+		".pem",
+		".key",
+		"id_rsa",
+		"id_ed25519",
+	}
+
+	// Bash commands that could modify protected files.
+	bashWritePatterns := []string{
+		"rm ", "mv ", "cp ", "> ",
+		"cat >", "echo >", "tee ",
+		"chmod ", "chown ",
+	}
+
+	isProtected := func(path string) bool {
+		lower := strings.ToLower(path)
+		for _, p := range protectedPatterns {
+			if strings.Contains(lower, p) {
+				return true
+			}
+		}
+		return false
+	}
+
+	api.OnToolCall(func(tc ext.ToolCallEvent, ctx ext.Context) *ext.ToolCallResult {
+		if !writeTools[tc.ToolName] {
+			return nil
+		}
+
+		// For Write/Edit: check the file_path / filePath field.
+		if tc.ToolName == "Write" || tc.ToolName == "Edit" {
+			var input map[string]any
+			if err := json.Unmarshal([]byte(tc.Input), &input); err != nil {
+				return nil
+			}
+			// Try both naming conventions.
+			filePath, _ := input["file_path"].(string)
+			if filePath == "" {
+				filePath, _ = input["filePath"].(string)
+			}
+			if isProtected(filePath) {
+				return &ext.ToolCallResult{
+					Block:  true,
+					Reason: "Blocked: writing to protected path: " + filePath,
+				}
+			}
+			return nil
+		}
+
+		// For Bash: check if the command references protected paths.
+		if tc.ToolName == "Bash" {
+			var input struct {
+				Command string `json:"command"`
+			}
+			if err := json.Unmarshal([]byte(tc.Input), &input); err != nil {
+				return nil
+			}
+
+			// Only check bash commands that look like file mutations.
+			isMutation := false
+			for _, pat := range bashWritePatterns {
+				if strings.Contains(input.Command, pat) {
+					isMutation = true
+					break
+				}
+			}
+			if !isMutation {
+				return nil
+			}
+
+			// Check if any protected pattern appears in the command.
+			for _, p := range protectedPatterns {
+				if strings.Contains(input.Command, p) {
+					return &ext.ToolCallResult{
+						Block:  true,
+						Reason: "Blocked: bash command references protected path (" + p + "): " + input.Command,
+					}
+				}
+			}
+		}
+
+		return nil
+	})
+}

examples/extensions/status-tools/helpers.go

@@ -0,0 +1,43 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"kit/ext"
+)
+
+// Helper functions for the status-tools extension
+// These are used by main.go but kept in a separate file
+// to demonstrate the multi-file extension pattern.
+
+// formatMemory converts bytes to human-readable format
+func formatMemory(bytes int64) string {
+	const (
+		KB = 1024
+		MB = 1024 * KB
+		GB = 1024 * MB
+	)
+
+	switch {
+	case bytes >= GB:
+		return fmt.Sprintf("%.2f GB", float64(bytes)/float64(GB))
+	case bytes >= MB:
+		return fmt.Sprintf("%.2f MB", float64(bytes)/float64(MB))
+	case bytes >= KB:
+		return fmt.Sprintf("%.2f KB", float64(bytes)/float64(KB))
+	default:
+		return fmt.Sprintf("%d B", bytes)
+	}
+}
+
+// showMemoryStatus displays memory usage (placeholder)
+func showMemoryStatus(ctx ext.Context) {
+	// This is a placeholder that would show memory stats
+	// In a real extension, you'd integrate with system metrics
+	ctx.PrintBlock(ext.PrintBlockOpts{
+		Text:        "Memory status monitoring not yet implemented",
+		BorderColor: "#f9e2af",
+		Subtitle:    "Memory",
+	})
+}

examples/extensions/status-tools/main.go

@@ -0,0 +1,49 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"kit/ext"
+)
+
+// Init registers the status tools extension.
+// This extension provides multiple status-related utilities as a
+// multi-file extension example.
+func Init(api ext.API) {
+	// Register a status bar widget that shows time
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		go func() {
+			ticker := time.NewTicker(time.Second)
+			defer ticker.Stop()
+			for range ticker.C {
+				ctx.SetStatus("clock", time.Now().Format("15:04:05"), 5)
+			}
+		}()
+	})
+
+	// Register a /status command
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "status",
+		Description: "Show system status information",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			stats := ctx.GetContextStats()
+			info := fmt.Sprintf(
+				"Model: %s\nTokens: %d/%d (%.1f%%)\nMessages: %d",
+				ctx.Model,
+				stats.EstimatedTokens,
+				stats.ContextLimit,
+				stats.UsagePercent*100,
+				stats.MessageCount,
+			)
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        info,
+				BorderColor: "#89b4fa",
+				Subtitle:    "System Status",
+			})
+			return "", nil
+		},
+	})
+}

examples/extensions/subagent-monitor_test.go

@@ -0,0 +1,159 @@
+package main
+
+import (
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/mark3labs/kit/internal/extensions"
+	"github.com/mark3labs/kit/pkg/extensions/test"
+)
+
+// TestSubagentMonitor_SessionStart verifies OnSessionStart initializes state
+// without panicking and properly guards nil ctx calls.
+func TestSubagentMonitor_SessionStart(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("../../.kit/extensions/subagent-monitor.go")
+
+	// Emit SessionStart - should not panic even with nil ctx functions
+	_, err := harness.Emit(extensions.SessionStartEvent{SessionID: "test-session"})
+	if err != nil {
+		t.Fatalf("SessionStart should not error: %v", err)
+	}
+}
+
+// TestSubagentMonitor_SubagentLifecycle verifies the full subagent lifecycle
+// creates entries and emits widget updates.
+func TestSubagentMonitor_SubagentLifecycle(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("../../.kit/extensions/subagent-monitor.go")
+
+	// Start session
+	_, err := harness.Emit(extensions.SessionStartEvent{SessionID: "test-session"})
+	if err != nil {
+		t.Fatalf("SessionStart should not error: %v", err)
+	}
+
+	// Emit SubagentStart
+	_, err = harness.Emit(extensions.SubagentStartEvent{
+		ToolCallID: "call-1",
+		Task:       "test task",
+	})
+	if err != nil {
+		t.Fatalf("SubagentStart should not error: %v", err)
+	}
+
+	// Emit a few chunks
+	for i := range 3 {
+		_, err = harness.Emit(extensions.SubagentChunkEvent{
+			ToolCallID: "call-1",
+			Task:       "test task",
+			ChunkType:  "text",
+			Content:    fmt.Sprintf("line %d", i),
+		})
+		if err != nil {
+			t.Fatalf("SubagentChunk %d should not error: %v", i, err)
+		}
+	}
+
+	// Emit tool call chunk
+	_, err = harness.Emit(extensions.SubagentChunkEvent{
+		ToolCallID: "call-1",
+		Task:       "test task",
+		ChunkType:  "tool_call",
+		ToolName:   "bash",
+	})
+	if err != nil {
+		t.Fatalf("SubagentChunk tool_call should not error: %v", err)
+	}
+
+	// Emit SubagentEnd
+	_, err = harness.Emit(extensions.SubagentEndEvent{
+		ToolCallID: "call-1",
+		Task:       "test task",
+		Response:   "done",
+	})
+	if err != nil {
+		t.Fatalf("SubagentEnd should not error: %v", err)
+	}
+
+	// Give time for cleanup goroutine
+	time.Sleep(100 * time.Millisecond)
+}
+
+// TestSubagentMonitor_MultipleSubagents verifies multiple parallel subagents.
+func TestSubagentMonitor_MultipleSubagents(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("../../.kit/extensions/subagent-monitor.go")
+
+	_, err := harness.Emit(extensions.SessionStartEvent{SessionID: "test-session"})
+	if err != nil {
+		t.Fatalf("SessionStart should not error: %v", err)
+	}
+
+	// Start 3 subagents
+	for i := 1; i <= 3; i++ {
+		_, err := harness.Emit(extensions.SubagentStartEvent{
+			ToolCallID: fmt.Sprintf("call-%d", i),
+			Task:       fmt.Sprintf("task %d", i),
+		})
+		if err != nil {
+			t.Fatalf("SubagentStart %d should not error: %v", i, err)
+		}
+	}
+
+	// Emit chunks for each
+	for i := 1; i <= 3; i++ {
+		_, err := harness.Emit(extensions.SubagentChunkEvent{
+			ToolCallID: fmt.Sprintf("call-%d", i),
+			Task:       fmt.Sprintf("task %d", i),
+			ChunkType:  "text",
+			Content:    fmt.Sprintf("output from agent %d", i),
+		})
+		if err != nil {
+			t.Fatalf("SubagentChunk %d should not error: %v", i, err)
+		}
+	}
+
+	// End all subagents
+	for i := 1; i <= 3; i++ {
+		_, err := harness.Emit(extensions.SubagentEndEvent{
+			ToolCallID: fmt.Sprintf("call-%d", i),
+			Task:       fmt.Sprintf("task %d", i),
+			Response:   "completed",
+		})
+		if err != nil {
+			t.Fatalf("SubagentEnd %d should not error: %v", i, err)
+		}
+	}
+
+	time.Sleep(100 * time.Millisecond)
+}
+
+// TestSubagentMonitor_SessionShutdown verifies shutdown doesn't panic
+// even with nil ctx functions.
+func TestSubagentMonitor_SessionShutdown(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("../../.kit/extensions/subagent-monitor.go")
+
+	// Start then shutdown
+	_, err := harness.Emit(extensions.SessionStartEvent{SessionID: "test-session"})
+	if err != nil {
+		t.Fatalf("SessionStart should not error: %v", err)
+	}
+
+	// Start a subagent
+	_, err = harness.Emit(extensions.SubagentStartEvent{
+		ToolCallID: "call-1",
+		Task:       "test task",
+	})
+	if err != nil {
+		t.Fatalf("SubagentStart should not error: %v", err)
+	}
+
+	// Shutdown - should not panic even with active subagent
+	_, err = harness.Emit(extensions.SessionShutdownEvent{})
+	if err != nil {
+		t.Fatalf("SessionShutdown should not error: %v", err)
+	}
+}

examples/extensions/subagent-test.go

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

examples/extensions/subagent-widget.go

@@ -0,0 +1,807 @@
+//go:build ignore
+
+// Subagent Widget — /sub, /subclear, /subrm, /subcont commands with live widgets
+//
+// Each /sub spawns a background Kit subagent as a subprocess with its own
+// live widget showing status, task, elapsed time, and last output line.
+// /subcont continues a finished subagent by passing conversation history.
+//
+// Commands:
+//
+//	/sub <task>              — spawn a new subagent
+//	/subcont <id> <prompt>   — continue subagent #<id>'s conversation
+//	/subrm <id>              — remove subagent #<id> widget
+//	/subclear                — clear all subagent widgets
+//
+// The LLM can also use tools: subagent_create, subagent_continue,
+// subagent_remove, subagent_list.
+//
+// Ported from https://github.com/disler/pi-vs-claude-code extensions/subagent-widget.ts
+//
+// Usage: kit -e examples/extensions/subagent-widget.go
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"kit/ext"
+)
+
+// subJSONOutput matches the JSON envelope produced by `kit --json`.
+type subJSONOutput struct {
+	Response string `json:"response"`
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type subState struct {
+	ID        int
+	Status    string // "running", "done", "error"
+	Task      string
+	Chunks    []string // accumulated output chunks
+	Elapsed   time.Duration
+	TurnCount int
+	History   string      // conversation history for /subcont
+	Proc      *os.Process // active process for killing
+	Removed   bool        // set when /subrm or /subclear removes this agent
+	mu        sync.Mutex
+}
+
+func (s *subState) appendChunk(chunk string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.Chunks = append(s.Chunks, chunk)
+}
+
+func (s *subState) setElapsed(d time.Duration) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.Elapsed = d
+}
+
+func (s *subState) setProc(p *os.Process) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.Proc = p
+}
+
+func (s *subState) snapshot() (int, string, string, string, time.Duration, int) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	fullText := strings.Join(s.Chunks, "")
+	return s.ID, s.Status, s.Task, fullText, s.Elapsed, s.TurnCount
+}
+
+// ---------------------------------------------------------------------------
+// Package-level state
+// ---------------------------------------------------------------------------
+
+var (
+	mu        sync.Mutex
+	latestCtx ext.Context
+	hasCtx    bool
+	agents    = map[int]*subState{}
+	nextID    = 1
+	kitBinary string
+)
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func findKitBinary() string {
+	if exe, err := os.Executable(); err == nil {
+		if _, err := os.Stat(exe); err == nil {
+			return exe
+		}
+	}
+	if p, err := exec.LookPath("kit"); err == nil {
+		return p
+	}
+	return "kit"
+}
+
+func truncate(s string, max int) string {
+	runes := []rune(s)
+	if len(runes) <= max {
+		return s
+	}
+	if max < 4 {
+		return string(runes[:max])
+	}
+	return string(runes[:max-3]) + "..."
+}
+
+func lastNonEmptyLine(text string) string {
+	lines := strings.Split(text, "\n")
+	for i := len(lines) - 1; i >= 0; i-- {
+		trimmed := strings.TrimSpace(lines[i])
+		if trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+// ---------------------------------------------------------------------------
+// Widget rendering
+// ---------------------------------------------------------------------------
+
+func updateWidgets() {
+	mu.Lock()
+	ctx := latestCtx
+	ok := hasCtx
+	agentsCopy := make([]*subState, 0, len(agents))
+	for _, s := range agents {
+		agentsCopy = append(agentsCopy, s)
+	}
+	mu.Unlock()
+	if !ok {
+		return
+	}
+
+	for _, state := range agentsCopy {
+		id, status, task, fullText, elapsed, turnCount := state.snapshot()
+
+		var icon, color string
+		switch status {
+		case "running":
+			icon = "●"
+			color = "#89b4fa" // blue
+		case "done":
+			icon = "✓"
+			color = "#a6e3a1" // green
+		default:
+			icon = "✗"
+			color = "#f38ba8" // red
+		}
+
+		taskPreview := truncate(task, 40)
+
+		turnLabel := ""
+		if turnCount > 1 {
+			turnLabel = fmt.Sprintf(" · Turn %d", turnCount)
+		}
+
+		header := fmt.Sprintf("%s Subagent #%d%s  %s  (%ds)",
+			icon, id, turnLabel, taskPreview, int(elapsed.Seconds()))
+
+		lastLine := truncate(lastNonEmptyLine(fullText), 80)
+
+		text := header
+		if lastLine != "" {
+			text += "\n  " + lastLine
+		}
+
+		ctx.SetWidget(ext.WidgetConfig{
+			ID:        fmt.Sprintf("subagent:%d", id),
+			Placement: ext.WidgetAbove,
+			Content:   ext.WidgetContent{Text: text},
+			Style:     ext.WidgetStyle{BorderColor: color},
+			Priority:  id,
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Subprocess spawning
+// ---------------------------------------------------------------------------
+
+func spawnAgent(state *subState) {
+	prompt := state.Task
+
+	state.mu.Lock()
+	history := state.History
+	state.mu.Unlock()
+
+	if history != "" {
+		prompt = "Previous conversation:\n" + history + "\n\nNew instruction: " + state.Task
+	}
+
+	args := []string{
+		"--json",
+		"--no-session",
+		"--no-extensions",
+		prompt,
+	}
+
+	cmd := exec.Command(kitBinary, args...)
+	cmd.Env = os.Environ()
+
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		state.mu.Lock()
+		state.Status = "error"
+		state.Chunks = append(state.Chunks, "Pipe error: "+err.Error())
+		state.mu.Unlock()
+		updateWidgets()
+		return
+	}
+
+	stderr, err := cmd.StderrPipe()
+	if err != nil {
+		state.mu.Lock()
+		state.Status = "error"
+		state.Chunks = append(state.Chunks, "Pipe error: "+err.Error())
+		state.mu.Unlock()
+		updateWidgets()
+		return
+	}
+
+	start := time.Now()
+	if err := cmd.Start(); err != nil {
+		state.mu.Lock()
+		state.Status = "error"
+		state.Chunks = append(state.Chunks, "Start error: "+err.Error())
+		state.mu.Unlock()
+		updateWidgets()
+		return
+	}
+
+	state.setProc(cmd.Process)
+
+	// Timer goroutine: update widget every second with elapsed time.
+	doneCh := make(chan struct{})
+	go func() {
+		ticker := time.NewTicker(1 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-doneCh:
+				return
+			case <-ticker.C:
+				state.setElapsed(time.Since(start))
+				updateWidgets()
+			}
+		}
+	}()
+
+	// Read stderr in background goroutine (live widget updates).
+	var readWg sync.WaitGroup
+	readWg.Add(1)
+	go func() {
+		defer readWg.Done()
+		scanner := bufio.NewScanner(stderr)
+		scanner.Buffer(make([]byte, 256*1024), 256*1024)
+		for scanner.Scan() {
+			line := scanner.Text()
+			if strings.TrimSpace(line) != "" {
+				state.appendChunk(line + "\n")
+				updateWidgets()
+			}
+		}
+	}()
+
+	// Read stdout into a separate buffer (JSON output from --json mode).
+	var stdoutBuf strings.Builder
+	scanner := bufio.NewScanner(stdout)
+	scanner.Buffer(make([]byte, 256*1024), 256*1024)
+	for scanner.Scan() {
+		stdoutBuf.WriteString(scanner.Text() + "\n")
+	}
+
+	// Wait for all pipe readers, then the process.
+	readWg.Wait()
+	waitErr := cmd.Wait()
+	close(doneCh) // stop timer
+
+	// Parse JSON output from --json mode to extract the response.
+	var result string
+	rawStdout := strings.TrimSpace(stdoutBuf.String())
+	var parsed subJSONOutput
+	if rawStdout != "" && json.Unmarshal([]byte(rawStdout), &parsed) == nil && parsed.Response != "" {
+		result = parsed.Response
+	} else {
+		// Fallback: use raw stdout (e.g. older kit binary without --json).
+		result = rawStdout
+	}
+
+	state.mu.Lock()
+	state.Elapsed = time.Since(start)
+	state.Proc = nil
+	if waitErr != nil {
+		state.Status = "error"
+	} else {
+		state.Status = "done"
+	}
+
+	// Save history for /subcont continuations (cap at 16 KB).
+	state.History += fmt.Sprintf("\n--- Turn %d ---\nTask: %s\nResult:\n%s\n",
+		state.TurnCount, state.Task, result)
+	if len(state.History) > 16000 {
+		state.History = state.History[len(state.History)-16000:]
+	}
+
+	removed := state.Removed
+	id := state.ID
+	elapsed := state.Elapsed
+	turnCount := state.TurnCount
+	task := state.Task
+	state.mu.Unlock()
+
+	updateWidgets()
+
+	// Don't deliver follow-up for agents removed via /subrm or /subclear.
+	if removed {
+		return
+	}
+
+	// Deliver result as a follow-up message so the LLM can act on it.
+	mu.Lock()
+	ctx := latestCtx
+	ok := hasCtx
+	mu.Unlock()
+
+	if ok {
+		resultText := result
+		if len(resultText) > 8000 {
+			resultText = resultText[:8000] + "\n\n... [truncated]"
+		}
+		turnSuffix := ""
+		if turnCount > 1 {
+			turnSuffix = fmt.Sprintf(" (Turn %d)", turnCount)
+		}
+		ctx.SendMessage(fmt.Sprintf(
+			"Subagent #%d%s finished \"%s\" in %ds.\n\nResult:\n%s",
+			id, turnSuffix, task, int(elapsed.Seconds()), resultText,
+		))
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Init
+// ---------------------------------------------------------------------------
+
+func Init(api ext.API) {
+	kitBinary = findKitBinary()
+
+	// ── Session Start: reset state, show help ──
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		mu.Lock()
+		latestCtx = ctx
+		hasCtx = true
+		mu.Unlock()
+
+		// Kill lingering agents from previous session.
+		mu.Lock()
+		for id, state := range agents {
+			state.mu.Lock()
+			if state.Proc != nil && state.Status == "running" {
+				state.Proc.Kill()
+			}
+			state.mu.Unlock()
+			ctx.RemoveWidget(fmt.Sprintf("subagent:%d", id))
+		}
+		agents = map[int]*subState{}
+		nextID = 1
+		mu.Unlock()
+
+		ctx.PrintInfo(
+			"Subagent Widget loaded\n\n" +
+				"/sub <task>              Spawn a new subagent\n" +
+				"/subcont <id> <prompt>   Continue a finished subagent\n" +
+				"/subrm <id>             Remove a subagent\n" +
+				"/subclear               Clear all subagents\n\n" +
+				"The LLM can also spawn subagents with the subagent_create tool.")
+	})
+
+	// ── Agent End: keep context fresh ──
+	api.OnAgentEnd(func(_ ext.AgentEndEvent, ctx ext.Context) {
+		mu.Lock()
+		latestCtx = ctx
+		mu.Unlock()
+	})
+
+	// ── Session Shutdown: cleanup ──
+	api.OnSessionShutdown(func(_ ext.SessionShutdownEvent, ctx ext.Context) {
+		mu.Lock()
+		defer mu.Unlock()
+		for id, state := range agents {
+			state.mu.Lock()
+			if state.Proc != nil && state.Status == "running" {
+				state.Proc.Kill()
+			}
+			state.mu.Unlock()
+			ctx.RemoveWidget(fmt.Sprintf("subagent:%d", id))
+		}
+		agents = map[int]*subState{}
+	})
+
+	// ── Tool: subagent_create ──
+	api.RegisterTool(ext.ToolDef{
+		Name: "subagent_create",
+		Description: `Spawn a background subagent to perform a task. Returns the subagent ID immediately while it runs in the background. Results are delivered as a follow-up message when the subagent finishes.
+
+Each subagent runs as a separate Kit subprocess with full tool access. Use this to delegate independent subtasks that can run in parallel with your main work.`,
+		Parameters: `{
+  "type": "object",
+  "properties": {
+    "task": {
+      "type": "string",
+      "description": "The complete task description for the subagent to perform"
+    }
+  },
+  "required": ["task"]
+}`,
+		Execute: func(input string) (string, error) {
+			var params struct {
+				Task string `json:"task"`
+			}
+			if err := json.Unmarshal([]byte(input), &params); err != nil {
+				return "", fmt.Errorf("invalid parameters: %w", err)
+			}
+			if strings.TrimSpace(params.Task) == "" {
+				return "", fmt.Errorf("task is required")
+			}
+
+			mu.Lock()
+			id := nextID
+			nextID++
+			state := &subState{
+				ID:        id,
+				Status:    "running",
+				Task:      params.Task,
+				TurnCount: 1,
+			}
+			agents[id] = state
+			mu.Unlock()
+
+			updateWidgets()
+			go spawnAgent(state)
+
+			return fmt.Sprintf("Subagent #%d spawned and running in background.", id), nil
+		},
+	})
+
+	// ── Tool: subagent_continue ──
+	api.RegisterTool(ext.ToolDef{
+		Name:        "subagent_continue",
+		Description: `Continue an existing subagent's conversation with a follow-up prompt. The subagent receives its previous conversation history as context. Use this to refine or extend a finished subagent's work.`,
+		Parameters: `{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "number",
+      "description": "The ID of the subagent to continue"
+    },
+    "prompt": {
+      "type": "string",
+      "description": "The follow-up prompt or new instructions"
+    }
+  },
+  "required": ["id", "prompt"]
+}`,
+		Execute: func(input string) (string, error) {
+			var params struct {
+				ID     int    `json:"id"`
+				Prompt string `json:"prompt"`
+			}
+			if err := json.Unmarshal([]byte(input), &params); err != nil {
+				return "", fmt.Errorf("invalid parameters: %w", err)
+			}
+
+			mu.Lock()
+			state, ok := agents[params.ID]
+			mu.Unlock()
+			if !ok {
+				return fmt.Sprintf("Error: No subagent #%d found.", params.ID), nil
+			}
+
+			state.mu.Lock()
+			if state.Status == "running" {
+				state.mu.Unlock()
+				return fmt.Sprintf("Error: Subagent #%d is still running.", params.ID), nil
+			}
+			state.Status = "running"
+			state.Task = params.Prompt
+			state.Chunks = nil
+			state.Elapsed = 0
+			state.TurnCount++
+			turn := state.TurnCount
+			state.mu.Unlock()
+
+			updateWidgets()
+			go spawnAgent(state)
+
+			return fmt.Sprintf("Subagent #%d continuing conversation in background (Turn %d).", params.ID, turn), nil
+		},
+	})
+
+	// ── Tool: subagent_remove ──
+	api.RegisterTool(ext.ToolDef{
+		Name:        "subagent_remove",
+		Description: "Remove a specific subagent. Kills it if currently running.",
+		Parameters: `{
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "number",
+      "description": "The ID of the subagent to remove"
+    }
+  },
+  "required": ["id"]
+}`,
+		Execute: func(input string) (string, error) {
+			var params struct {
+				ID int `json:"id"`
+			}
+			if err := json.Unmarshal([]byte(input), &params); err != nil {
+				return "", fmt.Errorf("invalid parameters: %w", err)
+			}
+
+			mu.Lock()
+			state, ok := agents[params.ID]
+			if !ok {
+				mu.Unlock()
+				return fmt.Sprintf("Error: No subagent #%d found.", params.ID), nil
+			}
+			delete(agents, params.ID)
+			mu.Unlock()
+
+			state.mu.Lock()
+			state.Removed = true
+			if state.Proc != nil && state.Status == "running" {
+				state.Proc.Kill()
+			}
+			state.mu.Unlock()
+
+			mu.Lock()
+			ctx := latestCtx
+			ok2 := hasCtx
+			mu.Unlock()
+			if ok2 {
+				ctx.RemoveWidget(fmt.Sprintf("subagent:%d", params.ID))
+			}
+
+			return fmt.Sprintf("Subagent #%d removed.", params.ID), nil
+		},
+	})
+
+	// ── Tool: subagent_list ──
+	api.RegisterTool(ext.ToolDef{
+		Name:        "subagent_list",
+		Description: "List all active and finished subagents with their IDs, tasks, and status.",
+		Parameters:  `{"type": "object", "properties": {}}`,
+		Execute: func(input string) (string, error) {
+			mu.Lock()
+			agentsCopy := make([]*subState, 0, len(agents))
+			for _, s := range agents {
+				agentsCopy = append(agentsCopy, s)
+			}
+			mu.Unlock()
+
+			if len(agentsCopy) == 0 {
+				return "No active subagents.", nil
+			}
+
+			var sb strings.Builder
+			sb.WriteString("Subagents:\n")
+			for _, s := range agentsCopy {
+				id, status, task, _, _, turnCount := s.snapshot()
+				fmt.Fprintf(&sb, "#%d [%s] (Turn %d) — %s\n",
+					id, strings.ToUpper(status), turnCount, task)
+			}
+			return sb.String(), nil
+		},
+	})
+
+	// ── Tool Renderers ──
+	api.RegisterToolRenderer(ext.ToolRenderConfig{
+		ToolName:    "subagent_create",
+		DisplayName: "Spawn Subagent",
+		BorderColor: "#89b4fa",
+		RenderHeader: func(toolArgs string, width int) string {
+			var args struct {
+				Task string `json:"task"`
+			}
+			if err := json.Unmarshal([]byte(toolArgs), &args); err != nil {
+				return ""
+			}
+			return truncate(args.Task, width)
+		},
+		RenderBody: func(toolResult string, isError bool, width int) string {
+			return truncate(toolResult, width)
+		},
+	})
+
+	api.RegisterToolRenderer(ext.ToolRenderConfig{
+		ToolName:    "subagent_continue",
+		DisplayName: "Continue Subagent",
+		BorderColor: "#cba6f7",
+		RenderHeader: func(toolArgs string, width int) string {
+			var args struct {
+				ID     int    `json:"id"`
+				Prompt string `json:"prompt"`
+			}
+			if err := json.Unmarshal([]byte(toolArgs), &args); err != nil {
+				return ""
+			}
+			return truncate(fmt.Sprintf("#%d: %s", args.ID, args.Prompt), width)
+		},
+		RenderBody: func(toolResult string, isError bool, width int) string {
+			return truncate(toolResult, width)
+		},
+	})
+
+	// ── Command: /sub <task> ──
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "sub",
+		Description: "Spawn a subagent with live widget: /sub <task>",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			hasCtx = true
+			mu.Unlock()
+
+			task := strings.TrimSpace(args)
+			if task == "" {
+				return "Usage: /sub <task>", nil
+			}
+
+			mu.Lock()
+			id := nextID
+			nextID++
+			state := &subState{
+				ID:        id,
+				Status:    "running",
+				Task:      task,
+				TurnCount: 1,
+			}
+			agents[id] = state
+			mu.Unlock()
+
+			updateWidgets()
+			go spawnAgent(state)
+
+			return fmt.Sprintf("Subagent #%d spawned: %s", id, truncate(task, 60)), nil
+		},
+	})
+
+	// ── Command: /subcont <id> <prompt> ──
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "subcont",
+		Description: "Continue subagent conversation: /subcont <id> <prompt>",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			hasCtx = true
+			mu.Unlock()
+
+			trimmed := strings.TrimSpace(args)
+			spaceIdx := strings.IndexByte(trimmed, ' ')
+			if spaceIdx < 0 {
+				return "Usage: /subcont <id> <prompt>", nil
+			}
+
+			num, err := strconv.Atoi(trimmed[:spaceIdx])
+			if err != nil {
+				return "Usage: /subcont <id> <prompt>", nil
+			}
+			prompt := strings.TrimSpace(trimmed[spaceIdx+1:])
+			if prompt == "" {
+				return "Usage: /subcont <id> <prompt>", nil
+			}
+
+			mu.Lock()
+			state, ok := agents[num]
+			mu.Unlock()
+			if !ok {
+				return fmt.Sprintf("No subagent #%d found. Use /sub to create one.", num), nil
+			}
+
+			state.mu.Lock()
+			if state.Status == "running" {
+				state.mu.Unlock()
+				return fmt.Sprintf("Subagent #%d is still running — wait for it to finish.", num), nil
+			}
+			state.Status = "running"
+			state.Task = prompt
+			state.Chunks = nil
+			state.Elapsed = 0
+			state.TurnCount++
+			turn := state.TurnCount
+			state.mu.Unlock()
+
+			updateWidgets()
+			go spawnAgent(state)
+
+			return fmt.Sprintf("Continuing subagent #%d (Turn %d): %s", num, turn, truncate(prompt, 50)), nil
+		},
+	})
+
+	// ── Command: /subrm <id> ──
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "subrm",
+		Description: "Remove a subagent widget: /subrm <id>",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			hasCtx = true
+			mu.Unlock()
+
+			num, err := strconv.Atoi(strings.TrimSpace(args))
+			if err != nil {
+				return "Usage: /subrm <id>", nil
+			}
+
+			mu.Lock()
+			state, ok := agents[num]
+			if !ok {
+				mu.Unlock()
+				return fmt.Sprintf("No subagent #%d found.", num), nil
+			}
+			delete(agents, num)
+			mu.Unlock()
+
+			state.mu.Lock()
+			state.Removed = true
+			killed := false
+			if state.Proc != nil && state.Status == "running" {
+				state.Proc.Kill()
+				killed = true
+			}
+			state.mu.Unlock()
+
+			ctx.RemoveWidget(fmt.Sprintf("subagent:%d", num))
+
+			if killed {
+				return fmt.Sprintf("Subagent #%d killed and removed.", num), nil
+			}
+			return fmt.Sprintf("Subagent #%d removed.", num), nil
+		},
+	})
+
+	// ── Command: /subclear ──
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "subclear",
+		Description: "Clear all subagent widgets",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			mu.Lock()
+			latestCtx = ctx
+			hasCtx = true
+			agentsCopy := make(map[int]*subState, len(agents))
+			for k, v := range agents {
+				agentsCopy[k] = v
+			}
+			agents = map[int]*subState{}
+			nextID = 1
+			mu.Unlock()
+
+			killed := 0
+			total := len(agentsCopy)
+			for id, state := range agentsCopy {
+				state.mu.Lock()
+				state.Removed = true
+				if state.Proc != nil && state.Status == "running" {
+					state.Proc.Kill()
+					killed++
+				}
+				state.mu.Unlock()
+				ctx.RemoveWidget(fmt.Sprintf("subagent:%d", id))
+			}
+
+			if total == 0 {
+				return "No subagents to clear.", nil
+			}
+			msg := fmt.Sprintf("Cleared %d subagent", total)
+			if total != 1 {
+				msg += "s"
+			}
+			if killed > 0 {
+				msg += fmt.Sprintf(" (%d killed)", killed)
+			}
+			msg += "."
+			return msg, nil
+		},
+	})
+}

examples/extensions/summarize.go

@@ -0,0 +1,93 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init adds a /summarize command that generates a concise summary of the
+// current conversation using a direct LLM completion. Demonstrates the
+// ctx.Complete API.
+//
+// The summary is displayed in a styled block and can optionally be saved
+// to the session via AppendEntry for later retrieval.
+//
+// Usage: kit -e examples/extensions/summarize.go
+func Init(api ext.API) {
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "summarize",
+		Description: "Summarize the current conversation",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			msgs := ctx.GetMessages()
+			if len(msgs) == 0 {
+				ctx.PrintInfo("Nothing to summarize — no messages yet.")
+				return "", nil
+			}
+
+			// Build a text representation of the conversation.
+			var parts []string
+			for _, m := range msgs {
+				content := m.Content
+				if len(content) > 2000 {
+					content = content[:1997] + "..."
+				}
+				parts = append(parts, fmt.Sprintf("[%s]: %s", m.Role, content))
+			}
+			conversation := strings.Join(parts, "\n\n")
+
+			ctx.PrintInfo("Generating summary...")
+
+			resp, err := ctx.Complete(ext.CompleteRequest{
+				System: `You are a concise summarization assistant. Summarize the conversation below in 3-5 bullet points. Focus on:
+- What was discussed or requested
+- Key decisions or outcomes
+- Any pending action items
+
+Be concise. Use plain text, no markdown headers.`,
+				Prompt: conversation,
+			})
+			if err != nil {
+				ctx.PrintError("Summary failed: " + err.Error())
+				return "", nil
+			}
+
+			summary := strings.TrimSpace(resp.Text)
+
+			ctx.PrintBlock(ext.PrintBlockOpts{
+				Text:        summary,
+				BorderColor: "#89b4fa",
+				Subtitle:    fmt.Sprintf("Summary (%d messages, %d tokens used)", len(msgs), resp.InputTokens+resp.OutputTokens),
+			})
+
+			// Persist the summary in the session for later retrieval.
+			ctx.AppendEntry("summary", summary)
+
+			return "", nil
+		},
+	})
+
+	// /summaries — list all saved summaries.
+	api.RegisterCommand(ext.CommandDef{
+		Name:        "summaries",
+		Description: "List saved conversation summaries",
+		Execute: func(args string, ctx ext.Context) (string, error) {
+			entries := ctx.GetEntries("summary")
+			if len(entries) == 0 {
+				ctx.PrintInfo("No summaries saved yet. Use /summarize to create one.")
+				return "", nil
+			}
+			for i, e := range entries {
+				ctx.PrintBlock(ext.PrintBlockOpts{
+					Text:        e.Data,
+					BorderColor: "#89b4fa",
+					Subtitle:    fmt.Sprintf("Summary #%d (%s)", i+1, e.Timestamp[:19]),
+				})
+			}
+			return "", nil
+		},
+	})
+}

examples/extensions/tool-logger_test.go

@@ -0,0 +1,358 @@
+package main
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/mark3labs/kit/internal/extensions"
+	"github.com/mark3labs/kit/pkg/extensions/test"
+)
+
+// Test that the tool-logger extension loads and registers handlers
+func TestToolLogger_Loads(t *testing.T) {
+	harness := test.New(t)
+	ext := harness.LoadFile("tool-logger.go")
+
+	if ext == nil {
+		t.Fatal("extension should not be nil")
+	}
+
+	// Verify all expected handlers are registered
+	test.AssertHasHandlers(t, harness, extensions.ToolCall)
+	test.AssertHasHandlers(t, harness, extensions.ToolResult)
+	test.AssertHasHandlers(t, harness, extensions.SessionStart)
+	test.AssertHasHandlers(t, harness, extensions.SessionShutdown)
+	test.AssertHasHandlers(t, harness, extensions.Input)
+}
+
+// Test that tool calls are logged (handlers run without errors)
+func TestToolLogger_ToolCall(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	// Emit a tool call event
+	result, err := harness.Emit(extensions.ToolCallEvent{
+		ToolName:   "Read",
+		ToolCallID: "call-123",
+		Input:      `{"file": "test.txt"}`,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Tool logger should not block any tools
+	test.AssertNotBlocked(t, result)
+}
+
+// Test that tool results are processed
+func TestToolLogger_ToolResult(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	content := "Hello, World!"
+	result, err := harness.Emit(extensions.ToolResultEvent{
+		ToolName: "Read",
+		Content:  content,
+		IsError:  false,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Tool logger should not modify results
+	if result != nil {
+		t.Error("expected nil result (no modification)")
+	}
+}
+
+// Test that error tool results are handled
+func TestToolLogger_ToolResultError(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	result, err := harness.Emit(extensions.ToolResultEvent{
+		ToolName: "Bash",
+		Content:  "command not found",
+		IsError:  true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if result != nil {
+		t.Error("expected nil result (no modification)")
+	}
+}
+
+// Test session start handler
+func TestToolLogger_SessionStart(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	_, err := harness.Emit(extensions.SessionStartEvent{
+		SessionID: "test-session-123",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Handler should run without errors (logs to file)
+	// Since file logging happens outside our mock, we just verify no errors
+}
+
+// Test session shutdown handler
+func TestToolLogger_SessionShutdown(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	_, err := harness.Emit(extensions.SessionShutdownEvent{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// Test the !time command
+func TestToolLogger_TimeCommand(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	result, err := harness.Emit(extensions.InputEvent{
+		Text:   "!time",
+		Source: "cli",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	test.AssertInputHandled(t, result, "handled")
+
+	// Verify PrintInfo was called with a time message
+	infos := harness.Context().GetPrintInfos()
+	found := false
+	for _, info := range infos {
+		if strings.Contains(info, "Current time:") {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Errorf("expected PrintInfo with 'Current time:', got: %v", infos)
+	}
+}
+
+// Test the !status command
+func TestToolLogger_StatusCommand(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	result, err := harness.Emit(extensions.InputEvent{
+		Text:   "!status",
+		Source: "cli",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	test.AssertInputHandled(t, result, "handled")
+
+	// Verify PrintBlock was called
+	blocks := harness.Context().PrintBlocks
+	if len(blocks) != 1 {
+		t.Fatalf("expected 1 PrintBlock call, got %d", len(blocks))
+	}
+
+	block := blocks[0]
+	if block.Subtitle != "tool-logger extension" {
+		t.Errorf("expected subtitle 'tool-logger extension', got %q", block.Subtitle)
+	}
+	if block.BorderColor != "#a6e3a1" {
+		t.Errorf("expected border color '#a6e3a1', got %q", block.BorderColor)
+	}
+	if !strings.Contains(block.Text, "Session active") {
+		t.Errorf("expected text to contain 'Session active', got %q", block.Text)
+	}
+}
+
+// Test that unknown commands are not handled
+func TestToolLogger_UnknownCommand(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	result, err := harness.Emit(extensions.InputEvent{
+		Text:   "!unknown",
+		Source: "cli",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if result != nil {
+		t.Errorf("expected nil result for unknown command, got %v", result)
+	}
+
+	// Verify no info/block prints for unknown commands
+	if len(harness.Context().GetPrintInfos()) != 0 {
+		t.Error("expected no PrintInfo calls for unknown command")
+	}
+	if len(harness.Context().PrintBlocks) != 0 {
+		t.Error("expected no PrintBlock calls for unknown command")
+	}
+}
+
+// Test regular text input (not a command)
+func TestToolLogger_RegularInput(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	result, err := harness.Emit(extensions.InputEvent{
+		Text:   "This is a normal message",
+		Source: "cli",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if result != nil {
+		t.Errorf("expected nil result for regular input, got %v", result)
+	}
+}
+
+// Test complete session flow
+func TestToolLogger_FullSession(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	// Simulate a full session
+	_, err := harness.Emit(extensions.SessionStartEvent{SessionID: "test"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Several tool calls
+	tools := []string{"Read", "Glob", "Grep", "Bash"}
+	for _, tool := range tools {
+		_, err := harness.Emit(extensions.ToolCallEvent{
+			ToolName: tool,
+			Input:    "{}",
+		})
+		if err != nil {
+			t.Fatalf("error for tool %s: %v", tool, err)
+		}
+
+		_, err = harness.Emit(extensions.ToolResultEvent{
+			ToolName: tool,
+			Content:  "result",
+			IsError:  false,
+		})
+		if err != nil {
+			t.Fatalf("error for tool result %s: %v", tool, err)
+		}
+	}
+
+	// User issues a command
+	_, err = harness.Emit(extensions.InputEvent{Text: "!time", Source: "cli"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	_, err = harness.Emit(extensions.SessionShutdownEvent{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Verify the !time command was handled
+	if len(harness.Context().GetPrintInfos()) != 1 {
+		t.Errorf("expected 1 PrintInfo call, got %d", len(harness.Context().GetPrintInfos()))
+	}
+}
+
+// Test that the extension handles file write errors gracefully
+func TestToolLogger_FileError(t *testing.T) {
+	// This test verifies the extension doesn't panic when file operations fail
+	// Since we can't easily mock os.OpenFile, we rely on the extension code
+	// properly checking for errors (which it does)
+
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	// Just verify the handlers run without panicking
+	_, err := harness.Emit(extensions.ToolCallEvent{ToolName: "Read", Input: "{}"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	_, err = harness.Emit(extensions.SessionStartEvent{SessionID: "test"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// Test concurrent tool calls (race condition check)
+func TestToolLogger_ConcurrentToolCalls(t *testing.T) {
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	// Run multiple tool calls concurrently
+	done := make(chan bool, 10)
+	for i := range 10 {
+		go func(index int) {
+			defer func() { done <- true }()
+
+			toolName := "Tool" + string(rune('0'+index))
+			_, err := harness.Emit(extensions.ToolCallEvent{
+				ToolName: toolName,
+				Input:    "{}",
+			})
+			if err != nil {
+				t.Errorf("error in goroutine %d: %v", index, err)
+			}
+		}(i)
+	}
+
+	// Wait for all goroutines
+	for range 10 {
+		<-done
+	}
+}
+
+// Test the actual log file is created and written to
+func TestToolLogger_LogFile(t *testing.T) {
+	logFile := "/tmp/kit-tool-log.txt"
+
+	// Clean up before test
+	_ = os.Remove(logFile)
+
+	harness := test.New(t)
+	harness.LoadFile("tool-logger.go")
+
+	// Emit events
+	_, _ = harness.Emit(extensions.SessionStartEvent{SessionID: "test"})
+	_, _ = harness.Emit(extensions.ToolCallEvent{ToolName: "Read", Input: "{}"})
+	_, _ = harness.Emit(extensions.ToolResultEvent{ToolName: "Read", Content: "data", IsError: false})
+
+	// Note: Since the extension writes to a real file and the test harness
+	// mocks the context, the file writes actually happen. Let's verify.
+
+	// Give it a moment for file operations
+	if _, err := os.Stat(logFile); err == nil {
+		// File exists - read and verify content
+		content, err := os.ReadFile(logFile)
+		if err != nil {
+			t.Logf("Could not read log file: %v", err)
+		} else {
+			contentStr := string(content)
+			if !strings.Contains(contentStr, "SESSION_START") {
+				t.Error("log file should contain SESSION_START")
+			}
+			if !strings.Contains(contentStr, "CALL tool=Read") {
+				t.Error("log file should contain CALL tool=Read")
+			}
+			if !strings.Contains(contentStr, "RESULT tool=Read") {
+				t.Error("log file should contain RESULT tool=Read")
+			}
+		}
+	} else {
+		t.Log("Note: Log file not created - this is expected since the extension writes directly to disk")
+	}
+}

examples/extensions/tool-renderer-demo.go

@@ -0,0 +1,116 @@
+//go:build ignore
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"kit/ext"
+)
+
+// Init demonstrates the custom tool rendering system. It registers
+// renderers that override how specific tools display their headers,
+// result bodies, display names, border colors, and backgrounds.
+//
+// Usage:
+//
+//	kit -e examples/extensions/tool-renderer-demo.go
+//
+// Then ask the agent to read a file or run a bash command to see
+// the custom rendering in action.
+func Init(api ext.API) {
+	// Custom renderer for the "read" tool: custom display name,
+	// blue border, compact filename-only header.
+	api.RegisterToolRenderer(ext.ToolRenderConfig{
+		ToolName:    "read",
+		DisplayName: "File",
+		BorderColor: "#89b4fa", // Catppuccin blue
+		RenderHeader: func(toolArgs string, width int) string {
+			var args map[string]any
+			if err := json.Unmarshal([]byte(toolArgs), &args); err != nil {
+				return ""
+			}
+			path, _ := args["path"].(string)
+			if path == "" {
+				return "" // fall back to default
+			}
+
+			// Show just the filename, not the full path.
+			parts := strings.Split(path, "/")
+			name := parts[len(parts)-1]
+
+			// Include offset/limit if present.
+			var extras []string
+			if offset, ok := args["offset"]; ok {
+				extras = append(extras, fmt.Sprintf("from line %v", offset))
+			}
+			if limit, ok := args["limit"]; ok {
+				extras = append(extras, fmt.Sprintf("max %v lines", limit))
+			}
+
+			result := name
+			if len(extras) > 0 {
+				result += " (" + strings.Join(extras, ", ") + ")"
+			}
+
+			if len(result) > width {
+				return result[:width-3] + "..."
+			}
+			return result
+		},
+		// RenderBody is nil — fall back to the builtin read renderer
+		// which already provides syntax-highlighted code blocks.
+	})
+
+	// Custom renderer for the "bash" tool: renamed to "Shell",
+	// dark background, custom header with $ prefix.
+	api.RegisterToolRenderer(ext.ToolRenderConfig{
+		ToolName:    "bash",
+		DisplayName: "Shell",
+		Background:  "#1e1e2e", // Dark background
+		BorderColor: "#a6e3a1", // Catppuccin green
+		RenderHeader: func(toolArgs string, width int) string {
+			var args map[string]any
+			if err := json.Unmarshal([]byte(toolArgs), &args); err != nil {
+				return ""
+			}
+			cmd, _ := args["command"].(string)
+			if cmd == "" {
+				return "" // fall back to default
+			}
+
+			// Show first line of command with a $ prefix.
+			lines := strings.SplitN(cmd, "\n", 2)
+			display := "$ " + lines[0]
+			if len(lines) > 1 {
+				display += " ..."
+			}
+
+			if len(display) > width {
+				return display[:width-3] + "..."
+			}
+			return display
+		},
+		RenderBody: func(toolResult string, isError bool, width int) string {
+			if isError {
+				return "" // fall back to default error rendering
+			}
+
+			// Count lines and show a summary at the end.
+			lines := strings.Split(toolResult, "\n")
+			lineCount := len(lines)
+
+			// Show the first few lines of output.
+			maxShow := 10
+			if lineCount <= maxShow {
+				return toolResult
+			}
+
+			shown := strings.Join(lines[:maxShow], "\n")
+			return fmt.Sprintf("%s\n\n[%d lines total, showing first %d]",
+				shown, lineCount, maxShow)
+		},
+	})
+}

examples/extensions/widget-status.go

@@ -0,0 +1,90 @@
+//go:build ignore
+
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"kit/ext"
+)
+
+// Init demonstrates the widget system by showing a persistent status
+// widget above the input area. The widget updates on each agent turn
+// to show a running count of tool calls and the last tool used.
+func Init(api ext.API) {
+	var toolCallCount int
+	var lastToolName string
+
+	// Show initial status widget when session starts.
+	api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
+		ctx.SetWidget(ext.WidgetConfig{
+			ID:        "widget-status:info",
+			Placement: ext.WidgetAbove,
+			Content: ext.WidgetContent{
+				Text: fmt.Sprintf("Session started  |  CWD: %s  |  Model: %s", ctx.CWD, ctx.Model),
+			},
+			Style: ext.WidgetStyle{
+				BorderColor: "#89b4fa",
+			},
+		})
+	})
+
+	// Update the widget after each tool call with a running count.
+	api.OnToolResult(func(tr ext.ToolResultEvent, ctx ext.Context) *ext.ToolResultResult {
+		toolCallCount++
+		lastToolName = tr.ToolName
+
+		status := "ok"
+		if tr.IsError {
+			status = "error"
+		}
+
+		ctx.SetWidget(ext.WidgetConfig{
+			ID:        "widget-status:info",
+			Placement: ext.WidgetAbove,
+			Content: ext.WidgetContent{
+				Text: fmt.Sprintf(
+					"Tools: %d calls  |  Last: %s (%s)  |  %s",
+					toolCallCount, lastToolName, status,
+					time.Now().Format("15:04:05"),
+				),
+			},
+			Style: ext.WidgetStyle{
+				BorderColor: "#a6e3a1",
+			},
+		})
+		return nil
+	})
+
+	// "!widget-off" — removes the status widget.
+	// "!widget-on"  — restores the status widget.
+	api.OnInput(func(ie ext.InputEvent, ctx ext.Context) *ext.InputResult {
+		switch ie.Text {
+		case "!widget-off":
+			ctx.RemoveWidget("widget-status:info")
+			ctx.PrintInfo("Status widget removed.")
+			return &ext.InputResult{Action: "handled"}
+
+		case "!widget-on":
+			ctx.SetWidget(ext.WidgetConfig{
+				ID:        "widget-status:info",
+				Placement: ext.WidgetAbove,
+				Content: ext.WidgetContent{
+					Text: fmt.Sprintf("Tools: %d calls  |  %s", toolCallCount, time.Now().Format("15:04:05")),
+				},
+				Style: ext.WidgetStyle{
+					BorderColor: "#a6e3a1",
+				},
+			})
+			ctx.PrintInfo("Status widget restored.")
+			return &ext.InputResult{Action: "handled"}
+		}
+		return nil
+	})
+
+	// Clean up widget on shutdown.
+	api.OnSessionShutdown(func(_ ext.SessionShutdownEvent, ctx ext.Context) {
+		ctx.RemoveWidget("widget-status:info")
+	})
+}

examples/sdk/README.md

@@ -0,0 +1,45 @@
+# SDK Examples
+
+These examples demonstrate how to use the Kit SDK (`pkg/kit`) to build agents programmatically in Go.
+
+## Examples
+
+### [basic](basic/)
+
+Shows core SDK usage: creating a Kit instance, sending prompts, overriding the model, subscribing to events (tool calls, streaming), and session management.
+
+```bash
+go run ./examples/sdk/basic
+```
+
+### [scripting](scripting/)
+
+A minimal script-friendly wrapper that takes a prompt from the command line and prints the response — useful for piping and automation.
+
+```bash
+go run ./examples/sdk/scripting "Explain what this repo does"
+```
+
+### [crypto-monitor](crypto-monitor/)
+
+A background agent that checks Bitcoin and Ethereum prices every 30 minutes and sends desktop notifications via `notify-send` (dbus). Demonstrates using the SDK for a long-running autonomous task with a single tool.
+
+```bash
+go run ./examples/sdk/crypto-monitor
+
+# Override the check interval:
+CRYPTO_INTERVAL=5m go run ./examples/sdk/crypto-monitor
+```
+
+## Getting Started
+
+```go
+import kit "github.com/mark3labs/kit/pkg/kit"
+
+host, err := kit.New(ctx, nil)        // uses ~/.kit.yml defaults
+defer host.Close()
+
+response, err := host.Prompt(ctx, "Hello!")
+```
+
+See the [SDK README](../../pkg/kit/README.md) for the full API reference.

examples/sdk/crypto-monitor/main.go

@@ -0,0 +1,85 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"os/signal"
+	"time"
+
+	kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+const systemPrompt = `You are a cryptocurrency price monitor. Your job is to:
+
+1. Fetch the current prices of Bitcoin and Ethereum using bash with curl
+2. Send a desktop notification with the results using notify-send
+
+To fetch prices, use this CoinGecko API endpoint (no API key needed):
+  curl -s 'https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd&include_24hr_change=true'
+
+To send a desktop notification:
+  notify-send -i dialog-information "Crypto Prices" "BTC: $XX,XXX (+X.X%)\nETH: $X,XXX (+X.X%)"
+
+Include the 24h percentage change in the notification. Use a green arrow (▲) for
+positive changes and a red arrow (▼) for negative. Format prices with commas.
+
+If the API call fails, send a notification about the failure instead.
+
+Always complete both steps: fetch then notify. Be concise — no commentary needed.`
+
+func main() {
+	interval := 30 * time.Minute
+	if os.Getenv("CRYPTO_INTERVAL") != "" {
+		d, err := time.ParseDuration(os.Getenv("CRYPTO_INTERVAL"))
+		if err == nil {
+			interval = d
+		}
+	}
+
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer cancel()
+
+	host, err := kit.New(ctx, &kit.Options{
+		SystemPrompt: systemPrompt,
+		Tools:        []kit.Tool{kit.NewBashTool()},
+		NoSession:    true,
+		Quiet:        true,
+	})
+	if err != nil {
+		log.Fatalf("Failed to create kit instance: %v", err)
+	}
+	defer func() { _ = host.Close() }()
+
+	fmt.Printf("Crypto price monitor started (every %s)\n", interval)
+	fmt.Println("Press Ctrl+C to stop")
+
+	// Run immediately on startup, then on each tick.
+	check(ctx, host)
+
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			check(ctx, host)
+		case <-ctx.Done():
+			fmt.Println("\nStopping price monitor")
+			return
+		}
+	}
+}
+
+func check(ctx context.Context, host *kit.Kit) {
+	fmt.Printf("[%s] Checking prices...\n", time.Now().Format("15:04:05"))
+
+	// Clear session so each check is independent.
+	host.ClearSession()
+
+	_, err := host.Prompt(ctx, "Fetch current Bitcoin and Ethereum prices and send a desktop notification.")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+	}
+}

go.mod

@@ -1,94 +1,96 @@
 module github.com/mark3labs/kit
 
-go 1.26.0
+go 1.26.1
 
 require (
-	charm.land/bubbles/v2 v2.0.0
-	charm.land/bubbletea/v2 v2.0.0
-	charm.land/fantasy v0.10.0
-	charm.land/lipgloss/v2 v2.0.0
-	github.com/charmbracelet/fang v0.4.4
-	github.com/mark3labs/mcp-go v0.44.0
+	charm.land/bubbles/v2 v2.1.0
+	charm.land/bubbletea/v2 v2.0.2
+	charm.land/fantasy v0.17.1
+	charm.land/huh/v2 v2.0.3
+	charm.land/lipgloss/v2 v2.0.2
+	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-20260330092749-0f94982c930b
+	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/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.47.1
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
-	golang.org/x/term v0.40.0
+	github.com/traefik/yaegi v0.16.1
+	golang.org/x/term v0.41.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
 	cloud.google.com/go v0.123.0 // indirect
-	cloud.google.com/go/auth v0.18.2 // 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/alecthomas/chroma/v2 v2.23.1 // indirect
-	github.com/atotto/clipboard v0.1.4 // indirect
-	github.com/aws/aws-sdk-go-v2 v1.41.2 // indirect
-	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.5 // indirect
-	github.com/aws/aws-sdk-go-v2/config v1.32.10 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.10 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.18 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.18 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.18 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.5 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.18 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.0.6 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.11 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.15 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.41.7 // indirect
-	github.com/aws/smithy-go v1.24.1 // indirect
-	github.com/aymanbagabas/go-udiff v0.4.0 // indirect
-	github.com/aymerick/douceur v0.2.0 // indirect
-	github.com/bahlo/generic-list-go v0.2.0 // indirect
-	github.com/buger/jsonparser v1.1.1 // 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.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
+	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 // indirect
+	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.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.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.2 // 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/log v0.4.2 // indirect
-	github.com/charmbracelet/ultraviolet v0.0.0-20260223171050-89c142e4aa73 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
-	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260223200540-d6a276319c45 // indirect
-	github.com/charmbracelet/x/exp/slice v0.0.0-20260223200540-d6a276319c45 // indirect
+	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260406091427-a791e22d5143 // indirect
+	github.com/charmbracelet/x/exp/ordered v0.1.0 // indirect
+	github.com/charmbracelet/x/exp/slice v0.0.0-20260406091427-a791e22d5143 // 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.0 // indirect
+	github.com/go-logfmt/logfmt v0.6.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	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.12 // indirect
-	github.com/googleapis/gax-go/v2 v2.17.0 // indirect
-	github.com/gorilla/css v1.0.1 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.14 // indirect
+	github.com/googleapis/gax-go/v2 v2.21.0 // indirect
 	github.com/gorilla/websocket v1.5.3 // indirect
-	github.com/invopop/jsonschema v0.13.0 // indirect
-	github.com/kaptinlin/go-i18n v0.2.11 // indirect
-	github.com/kaptinlin/jsonpointer v0.4.16 // indirect
-	github.com/kaptinlin/jsonschema v0.7.3 // indirect
-	github.com/kaptinlin/messageformat-go v0.4.18 // indirect
-	github.com/mailru/easyjson v0.9.1 // indirect
-	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
+	github.com/kaptinlin/go-i18n v0.3.1 // 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/mitchellh/hashstructure/v2 v2.0.2 // indirect
 	github.com/muesli/mango v0.2.0 // indirect
 	github.com/muesli/mango-cobra v1.3.0 // indirect
 	github.com/muesli/mango-pflag v0.2.0 // indirect
-	github.com/muesli/reflow v0.3.0 // indirect
 	github.com/muesli/roff v0.1.0 // indirect
-	github.com/openai/openai-go/v2 v2.7.1 // indirect
-	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/pelletier/go-toml/v2 v2.3.0 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
@@ -97,46 +99,42 @@ require (
 	github.com/tidwall/match v1.2.0 // indirect
 	github.com/tidwall/pretty v1.2.1 // indirect
 	github.com/tidwall/sjson v1.2.5 // indirect
-	github.com/traefik/yaegi v0.16.1 // indirect
-	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
-	github.com/yuin/goldmark v1.7.16 // indirect
-	github.com/yuin/goldmark-emoji v1.0.6 // indirect
+	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.65.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
-	go.opentelemetry.io/otel v1.40.0 // indirect
-	go.opentelemetry.io/otel/metric v1.40.0 // indirect
-	go.opentelemetry.io/otel/trace v1.40.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.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.48.0 // indirect
-	golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa // indirect
-	golang.org/x/net v0.50.0 // indirect
-	golang.org/x/oauth2 v0.35.0 // indirect
-	golang.org/x/time v0.14.0 // indirect
-	google.golang.org/api v0.269.0 // indirect
-	google.golang.org/genai v1.47.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260223185530-2f722ef697dc // indirect
-	google.golang.org/grpc v1.79.1 // indirect
+	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/oauth2 v0.36.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
+	google.golang.org/api v0.275.0 // indirect
+	google.golang.org/genai v1.52.1 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260406210006-6f92a3bedf2d // 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/glamour v0.10.0
-	github.com/charmbracelet/x/ansi v0.11.6 // indirect
+	github.com/charmbracelet/x/ansi v0.11.6
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/mattn/go-runewidth v0.0.20 // indirect
+	github.com/lucasb-eyer/go-colorful v1.4.0 // 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.19.0 // indirect
-	golang.org/x/sys v0.41.0 // indirect
-	golang.org/x/text v0.34.0 // indirect
+	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/text v0.35.0
 )

go.sum

@@ -1,27 +1,29 @@
-charm.land/bubbles/v2 v2.0.0 h1:tE3eK/pHjmtrDiRdoC9uGNLgpopOd8fjhEe31B/ai5s=
-charm.land/bubbles/v2 v2.0.0/go.mod h1:rCHoleP2XhU8um45NTuOWBPNVHxnkXKTiZqcclL/qOI=
-charm.land/bubbletea/v2 v2.0.0 h1:p0d6CtWyJXJ9GfzMpUUqbP/XUUhhlk06+vCKWmox1wQ=
-charm.land/bubbletea/v2 v2.0.0/go.mod h1:3LRff2U4WIYXy7MTxfbAQ+AdfM3D8Xuvz2wbsOD9OHQ=
-charm.land/fantasy v0.10.0 h1:6PD+1rrsCgLIG1n+PAZp/gHiC0dltU0cvb7c8zUKyu8=
-charm.land/fantasy v0.10.0/go.mod h1:KIeNQUpJTswwpY0P6HJsr3LBFgfTDb8FDpOdVQMsKqY=
-charm.land/lipgloss/v2 v2.0.0 h1:sd8N/B3x892oiOjFfBQdXBQp3cAkvjGaU5TvVZC3ivo=
-charm.land/lipgloss/v2 v2.0.0/go.mod h1:w6SnmsBFBmEFBodiEDurGS/sdUY/u1+v72DqUzc6J14=
+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/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=
 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.18.2 h1:+Nbt5Ev0xEqxlNjd6c+yYUeosQ5TtEUaNcN/3FozlaM=
-cloud.google.com/go/auth v0.18.2/go.mod h1:xD+oY7gcahcu7G2SG2DsBerfFxgPAJz17zz2joOFF3M=
+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=
@@ -32,74 +34,78 @@ github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs
 github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
 github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
-github.com/aws/aws-sdk-go-v2 v1.41.2 h1:LuT2rzqNQsauaGkPK/7813XxcZ3o3yePY0Iy891T2ls=
-github.com/aws/aws-sdk-go-v2 v1.41.2/go.mod h1:IvvlAZQXvTXznUPfRVfryiG1fbzE2NGK6m9u39YQ+S4=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.5 h1:zWFmPmgw4sveAYi1mRqG+E/g0461cJ5M4bJ8/nc6d3Q=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.5/go.mod h1:nVUlMLVV8ycXSb7mSkcNu9e3v/1TJq2RTlrPwhYWr5c=
-github.com/aws/aws-sdk-go-v2/config v1.32.10 h1:9DMthfO6XWZYLfzZglAgW5Fyou2nRI5CuV44sTedKBI=
-github.com/aws/aws-sdk-go-v2/config v1.32.10/go.mod h1:2rUIOnA2JaiqYmSKYmRJlcMWy6qTj1vuRFscppSBMcw=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.10 h1:EEhmEUFCE1Yhl7vDhNOI5OCL/iKMdkkYFTRpZXNw7m8=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.10/go.mod h1:RnnlFCAlxQCkN2Q379B67USkBMu1PipEEiibzYN5UTE=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.18 h1:Ii4s+Sq3yDfaMLpjrJsqD6SmG/Wq/P5L/hw2qa78UAY=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.18/go.mod h1:6x81qnY++ovptLE6nWQeWrpXxbnlIex+4H4eYYGcqfc=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.18 h1:F43zk1vemYIqPAwhjTjYIz0irU2EY7sOb/F5eJ3HuyM=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.18/go.mod h1:w1jdlZXrGKaJcNoL+Nnrj+k5wlpGXqnNrKoP22HvAug=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.18 h1:xCeWVjj0ki0l3nruoyP2slHsGArMxeiiaoPN5QZH6YQ=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.18/go.mod h1:r/eLGuGCBw6l36ZRWiw6PaZwPXb6YOj+i/7MizNl5/k=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 h1:WKuaxf++XKWlHWu9ECbMlha8WOEGm0OUEZqm4K/Gcfk=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4/go.mod h1:ZWy7j6v1vWGmPReu0iSGvRiise4YI5SkR3OHKTZ6Wuc=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.5 h1:CeY9LUdur+Dxoeldqoun6y4WtJ3RQtzk0JMP2gfUay0=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.5/go.mod h1:AZLZf2fMaahW5s/wMRciu1sYbdsikT/UHwbUjOdEVTc=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.18 h1:LTRCYFlnnKFlKsyIQxKhJuDuA3ZkrDQMRYm6rXiHlLY=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.18/go.mod h1:XhwkgGG6bHSd00nO/mexWTcTjgd6PjuvWQMqSn2UaEk=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.6 h1:MzORe+J94I+hYu2a6XmV5yC9huoTv8NRcCrUNedDypQ=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.6/go.mod h1:hXzcHLARD7GeWnifd8j9RWqtfIgxj4/cAtIVIK7hg8g=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.11 h1:7oGD8KPfBOJGXiCoRKrrrQkbvCp8N++u36hrLMPey6o=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.11/go.mod h1:0DO9B5EUJQlIDif+XJRWCljZRKsAFKh3gpFz7UnDtOo=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.15 h1:edCcNp9eGIUDUCrzoCu1jWAXLGFIizeqkdkKgRlJwWc=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.15/go.mod h1:lyRQKED9xWfgkYC/wmmYfv7iVIM68Z5OQ88ZdcV1QbU=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.7 h1:NITQpgo9A5NrDZ57uOWj+abvXSb83BbyggcUBVksN7c=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.7/go.mod h1:sks5UWBhEuWYDPdwlnRFn1w7xWdH29Jcpe+/PJQefEs=
-github.com/aws/smithy-go v1.24.1 h1:VbyeNfmYkWoxMVpGUAbQumkODcYmfMRfZ8yQiH30SK0=
-github.com/aws/smithy-go v1.24.1/go.mod h1:LEj2LM3rBRQJxPZTB4KuzZkaZYnZPnvgIhb4pu07mx0=
+github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
+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.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=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21/go.mod h1:A/kJFst/nm//cyqonihbdpQZwiUhhzpqTsdbhDdRF9c=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 h1:PEgGVtPoB6NTpPrBgqSE5hE/o47Ij9qk/SEZFbUOe9A=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21/go.mod h1:p+hz+PRAYlY3zcpJhPwXlLC4C+kqn70WIHwnzAfs6ps=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 h1:qYQ4pzQ2Oz6WpQ8T3HvGHnZydA72MnLuFK9tJwmrbHw=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6/go.mod h1:O3h0IK87yXci+kg6flUKzJnWeziQUKciKrLjcatSNcY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3xgIJMSC8S6hEVq+38DcvUlgFY0FM6mSI5oto=
+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.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.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.0 h1:TKnLPh7IbnizJIBKFWa9mKayRUBQ9Kh1BPCk6w2PnYM=
-github.com/aymanbagabas/go-udiff v0.4.0/go.mod h1:0L9PGwj20lrtmEMeyw4WKJ/TMyDtvAoK9bf2u/mNo3w=
-github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuPk=
-github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
-github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
-github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
-github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
-github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
+github.com/aymanbagabas/go-udiff v0.4.1 h1:OEIrQ8maEeDBXQDoGCbbTTXYJMYRCRO1fnodZ12Gv5o=
+github.com/aymanbagabas/go-udiff v0.4.1/go.mod h1:0L9PGwj20lrtmEMeyw4WKJ/TMyDtvAoK9bf2u/mNo3w=
+github.com/catppuccin/go v0.3.0 h1:d+0/YicIq+hSTo5oPuRi5kOpqkVA5tAsU6dNhvRu+aY=
+github.com/catppuccin/go v0.3.0/go.mod h1:8IHJuMGaUUjQM82qBrGNBv7LFq6JI3NnQCF6MOlZjpc=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/charmbracelet/anthropic-sdk-go v0.0.0-20260223140439-63879b0b8dab h1:J7XQLgl9sefgTnTGrmX3xqvp5o6MCiBzEjGv5igAlc4=
 github.com/charmbracelet/anthropic-sdk-go v0.0.0-20260223140439-63879b0b8dab/go.mod h1:hqlYqR7uPKOKfnNeicUbZp0Ps0GeYFlKYtwh5HGDCx8=
-github.com/charmbracelet/colorprofile v0.4.2 h1:BdSNuMjRbotnxHSfxy+PCSa4xAmz7szw70ktAtWRYrY=
-github.com/charmbracelet/colorprofile v0.4.2/go.mod h1:0rTi81QpwDElInthtrQ6Ni7cG0sDtwAd4C4le060fT8=
-github.com/charmbracelet/fang v0.4.4 h1:G4qKxF6or/eTPgmAolwPuRNyuci3hTUGGX1rj1YkHJY=
-github.com/charmbracelet/fang v0.4.4/go.mod h1:P5/DNb9DddQ0Z0dbc0P3ol4/ix5Po7Ofr2KMBfAqoCo=
-github.com/charmbracelet/glamour v0.10.0 h1:MtZvfwsYCx8jEPFJm3rIBFIMZUfUJ765oX8V6kXldcY=
-github.com/charmbracelet/glamour v0.10.0/go.mod h1:f+uf+I/ChNmqo087elLnVdCiVgjSKWuXa/l6NU2ndYk=
+github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
+github.com/charmbracelet/colorprofile v0.4.3/go.mod h1:/zT4BhpD5aGFpqQQqw7a+VtHCzu+zrQtt1zhMt9mR4Q=
+github.com/charmbracelet/fang v1.0.0 h1:jESBY40agJOlLYnnv9jE0mLqDGTxEk0hkOnx7YGyRlQ=
+github.com/charmbracelet/fang v1.0.0/go.mod h1:P5/DNb9DddQ0Z0dbc0P3ol4/ix5Po7Ofr2KMBfAqoCo=
 github.com/charmbracelet/harmonica v0.2.0 h1:8NxJWRWg/bzKqqEaaeFNipOu77YR5t8aSwG4pgaUBiQ=
 github.com/charmbracelet/harmonica v0.2.0/go.mod h1:KSri/1RMQOZLbw7AHqgcBycp8pgJnQMYYT8QZRqZ1Ao=
 github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 h1:ZR7e0ro+SZZiIZD7msJyA+NjkCNNavuiPBLgerbOziE=
 github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834/go.mod h1:aKC/t2arECF6rNOnaKaVU6y4t4ZeHQzqfxedE/VkVhA=
-github.com/charmbracelet/log v0.4.2 h1:hYt8Qj6a8yLnvR+h7MwsJv/XvmBJXiueUcI3cIxsyig=
-github.com/charmbracelet/log v0.4.2/go.mod h1:qifHGX/tc7eluv2R6pWIpyHDDrrb/AG71Pf2ysQu5nw=
-github.com/charmbracelet/ultraviolet v0.0.0-20260223171050-89c142e4aa73 h1:Af/L28Xh+pddhouT/6lJ7IAIYfu5tWJOB0iqt+mXsYM=
-github.com/charmbracelet/ultraviolet v0.0.0-20260223171050-89c142e4aa73/go.mod h1:E6/0abq9uG2SnM8IbLB9Y5SW09uIgfaFETk8aRzgXUQ=
+github.com/charmbracelet/log v1.0.0 h1:HVVVMmfOorfj3BA9i8X8UL69Hoz9lI0PYwXfJvOdRc4=
+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/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
 github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260223200540-d6a276319c45 h1:t/EWU3ZOrVxmr2d19f+1wnWr92p1O82oOTm7ASxodsA=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260223200540-d6a276319c45/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
+github.com/charmbracelet/x/conpty v0.1.1 h1:s1bUxjoi7EpqiXysVtC+a8RrvPPNcNvAjfi4jxsAuEs=
+github.com/charmbracelet/x/conpty v0.1.1/go.mod h1:OmtR77VODEFbiTzGE9G1XiRJAga6011PIm4u5fTNZpk=
+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-20260406091427-a791e22d5143 h1:zmBor0ftFNqVFp9U59ZoEDRUCIYSGOGSIfGGkNZRufs=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260406091427-a791e22d5143/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f h1:pk6gmGpCE7F3FcjaOEKYriCvpmIN4+6OS/RD0vm4uIA=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f/go.mod h1:IfZAMTHB6XkZSeXUqriemErjAWCCzT0LwjKFYCZyw0I=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260223200540-d6a276319c45 h1:jgQlAnMmwbjtvd91AzjWWFtwpIZ2P/Nspx5zyrhmPec=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260223200540-d6a276319c45/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
+github.com/charmbracelet/x/exp/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-20260406091427-a791e22d5143 h1:aEppolah2k9c0LzKX2fk5ryuyQ0Lq8kCOjkvMw1b8o4=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260406091427-a791e22d5143/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=
 github.com/charmbracelet/x/json v0.2.0/go.mod h1:opFIflx2YgXgi49xVUu8gEQ21teFAxyMwvOiZhIvWNM=
 github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
@@ -108,19 +114,27 @@ github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8
 github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo=
 github.com/charmbracelet/x/windows v0.2.2 h1:IofanmuvaxnKHuV04sC0eBy/smG6kIKrWG2/jYn2GuM=
 github.com/charmbracelet/x/windows v0.2.2/go.mod h1:/8XtdKZzedat74NQFn0NGlGL4soHB0YQZrETF96h75k=
+github.com/charmbracelet/x/xpty v0.1.3 h1:eGSitii4suhzrISYH50ZfufV3v085BXQwIytcOdFSsw=
+github.com/charmbracelet/x/xpty v0.1.3/go.mod h1:poPYpWuLDBFCKmKLDnhBp51ATa0ooD8FhypRwEFtH3Y=
 github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSEFgwIwO+UVM8=
 github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
 github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os8IaYg++6uMOdKK83QtkkvJik=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=
+github.com/coder/acp-go-sdk v0.6.3 h1:LsXQytehdjKIYJnoVWON/nf7mqbiarnyuyE3rrjBsXQ=
+github.com/coder/acp-go-sdk v0.6.3/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
+github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ=
 github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/dnaeon/go-vcr v1.2.0 h1:zHCHvJYTMh1N7xnV7zf1m1GPBF9Ad0Jk/whtQ1663qI=
 github.com/dnaeon/go-vcr v1.2.0/go.mod h1:R4UdLID7HZT3taECzJs4YgbbH6PIGXB6W/sc5OLb6RQ=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/envoyproxy/go-control-plane v0.14.0 h1:hbG2kr4RuFj222B6+7T83thSPqLjwBIfQawTkC++2HA=
 github.com/envoyproxy/go-control-plane/envoy v1.37.0 h1:u3riX6BoYRfF4Dr7dwSOroNfdSbEPe9Yyl09/B6wBrQ=
 github.com/envoyproxy/go-control-plane/envoy v1.37.0/go.mod h1:DReE9MMrmecPy+YvQOAOHNYMALuowAnbjjEMkkWOi6A=
@@ -134,8 +148,8 @@ github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
 github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
-github.com/go-logfmt/logfmt v0.6.0 h1:wGYYu3uicYdqXVgoYbvnkrPVXkuLM1p1ifugDMEdRi4=
-github.com/go-logfmt/logfmt v0.6.0/go.mod h1:WYhtIu8zTZfxdn5+rREduYbwxfcBr/Vr6KEVveWlfTs=
+github.com/go-logfmt/logfmt v0.6.1 h1:4hvbpePJKnIzH1B+8OR/JPbTx37NktoI9LE2QZBBkvE=
+github.com/go-logfmt/logfmt v0.6.1/go.mod h1:EV2pOAQoZaT1ZXZbqDl5hrymndi4SY9ED9/z6CO0XAk=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
@@ -151,51 +165,50 @@ github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
+github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
 github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-github.com/googleapis/enterprise-certificate-proxy v0.3.12 h1:Fg+zsqzYEs1ZnvmcztTYxhgCBsx3eEhEwQ1W/lHq/sQ=
-github.com/googleapis/enterprise-certificate-proxy v0.3.12/go.mod h1:vqVt9yG9480NtzREnTlmGSBmFrA+bzb0yl0TxoBQXOg=
-github.com/googleapis/gax-go/v2 v2.17.0 h1:RksgfBpxqff0EZkDWYuz9q/uWsTVz+kf43LsZ1J6SMc=
-github.com/googleapis/gax-go/v2 v2.17.0/go.mod h1:mzaqghpQp4JDh3HvADwrat+6M3MOIDp5YKHhb9PAgDY=
-github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
-github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
+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.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/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
-github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
-github.com/kaptinlin/go-i18n v0.2.11 h1:OayNt8mWt8nDaqAOp09/C1VG9Y5u8LpQnnxbyGARDV4=
-github.com/kaptinlin/go-i18n v0.2.11/go.mod h1:pVcu9qsW5pOIOoZFJXesRYmLos1vMQrby70JPAoWmJU=
-github.com/kaptinlin/jsonpointer v0.4.16 h1:Ux4w4FY+uLv+K+TxaCJtM/TpPv+1+eS6gH4Z9/uhOuA=
-github.com/kaptinlin/jsonpointer v0.4.16/go.mod h1:SsfsjqnHG5zuKo1DTBzk1VknaHlL4osHw+X9kZKukpU=
-github.com/kaptinlin/jsonschema v0.7.3 h1:kyIydij76ORiSxmfy0xFYy0cOx8MwG6pyyaSoQshsK4=
-github.com/kaptinlin/jsonschema v0.7.3/go.mod h1:Ys6zr+W6/1330FzZEouFrAYImK+AmYt5HQVTHQQXQo8=
-github.com/kaptinlin/messageformat-go v0.4.18 h1:RBlHVWgZyoxTcUgGWBsl2AcyScq/urqbLZvzgryTmSI=
-github.com/kaptinlin/messageformat-go v0.4.18/go.mod h1:ntI3154RnqJgr7GaC+vZBnIExl2V3sv9selvRNNEM24=
+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.3.1 h1:plXi3XQE1aYamFi8TU0K6actODmw2+5FSobmhTkfQ/0=
+github.com/kaptinlin/go-i18n v0.3.1/go.mod h1:ZRoAHj7elWYamfbv7wev7Ajch6LOzjtBaq8nWe8HIVk=
+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/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=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
-github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
-github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/mailru/easyjson v0.9.1 h1:LbtsOm5WAswyWbvTEOqhypdPeZzHavpZx96/n553mR8=
-github.com/mailru/easyjson v0.9.1/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU=
-github.com/mark3labs/mcp-go v0.44.0 h1:OlYfcVviAnwNN40QZUrrzU0QZjq3En7rCU5X09a/B7I=
-github.com/mark3labs/mcp-go v0.44.0/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/mattn/go-runewidth v0.0.12/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
-github.com/mattn/go-runewidth v0.0.20 h1:WcT52H91ZUAwy8+HUkdM3THM6gXqXuLJi9O3rjcQQaQ=
-github.com/mattn/go-runewidth v0.0.20/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
-github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
-github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
+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.47.1 h1:A9sJJ20mscl/ssLYHjodfaoBmq6uuhMG7pAPNYaQymQ=
+github.com/mark3labs/mcp-go v0.47.1/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=
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/muesli/mango v0.2.0 h1:iNNc0c5VLQ6fsMgAqGQofByNUBH2Q2nEbD6TaI+5yyQ=
@@ -204,24 +217,18 @@ github.com/muesli/mango-cobra v1.3.0 h1:vQy5GvPg3ndOSpduxutqFoINhWk3vD5K2dXo5E8p
 github.com/muesli/mango-cobra v1.3.0/go.mod h1:Cj1ZrBu3806Qw7UjxnAUgE+7tllUBj1NCLQDwwGx19E=
 github.com/muesli/mango-pflag v0.2.0 h1:QViokgKDZQCzKhYe1zH8D+UlPJzBSGoP9yx0hBG0t5k=
 github.com/muesli/mango-pflag v0.2.0/go.mod h1:X9LT1p/pbGA1wjvEbtwnixujKErkP0jVmrxwrw3fL0Y=
-github.com/muesli/reflow v0.3.0 h1:IFsN6K9NfGtjeggFP+68I4chLZV2yIKsXJFNZ+eWh6s=
-github.com/muesli/reflow v0.3.0/go.mod h1:pbwTDkVPibjO2kyvBQRBxTWEEGDGq0FlB1BIKtnHY/8=
 github.com/muesli/roff v0.1.0 h1:YD0lalCotmYuF5HhZliKWlIx7IEhiXeSfq7hNjFqGF8=
 github.com/muesli/roff v0.1.0/go.mod h1:pjAHQM9hdUUwm/krAfrLGgJkXJ+YuhtsfZ42kieB2Ig=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
-github.com/openai/openai-go/v2 v2.7.1 h1:/tfvTJhfv7hTSL8mWwc5VL4WLLSDL5yn9VqVykdu9r8=
-github.com/openai/openai-go/v2 v2.7.1/go.mod h1:jrJs23apqJKKbT+pqtFgNKpRju/KP9zpUTZhz3GElQE=
-github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
-github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pelletier/go-toml/v2 v2.3.0 h1:k59bC/lIZREW0/iVaQR8nDHxVq8OVlIzYCOJf421CaM=
+github.com/pelletier/go-toml/v2 v2.3.0/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo=
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
-github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
@@ -257,63 +264,62 @@ github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
 github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
 github.com/traefik/yaegi v0.16.1 h1:f1De3DVJqIDKmnasUF6MwmWv1dSEEat0wcpXhD2On3E=
 github.com/traefik/yaegi v0.16.1/go.mod h1:4eVhbPb3LnD2VigQjhYbEJ69vDRFdT2HQNrXx8eEwUY=
-github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
-github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
-github.com/yuin/goldmark v1.7.16 h1:n+CJdUxaFMiDUNnWC3dMWCIQJSkxH4uz3ZwQBkAlVNE=
-github.com/yuin/goldmark v1.7.16/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
-github.com/yuin/goldmark-emoji v1.0.6 h1:QWfF2FYaXwL74tfGOW5izeiZepUDroDJfWubQI9HTHs=
-github.com/yuin/goldmark-emoji v1.0.6/go.mod h1:ukxJDKFpdFb5x0a5HqbdlcKtebh086iJpI31LTKmWuA=
+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.65.0 h1:XmiuHzgJt067+a6kwyAzkhXooYVv3/TOw9cM2VfJgUM=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.65.0/go.mod h1:KDgtbWKTQs4bM+VPUr6WlL9m/WXcmkCcBlIzqxPGzmI=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 h1:7iP2uCb7sGddAr30RRS6xjKy7AZ2JtTOPA3oolgVSw8=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0/go.mod h1:c7hN3ddxs/z6q9xwvfLPk+UHlWRQyaeR1LdgfL/66l0=
-go.opentelemetry.io/otel v1.40.0 h1:oA5YeOcpRTXq6NN7frwmwFR0Cn3RhTVZvXsP4duvCms=
-go.opentelemetry.io/otel v1.40.0/go.mod h1:IMb+uXZUKkMXdPddhwAHm6UfOwJyh4ct1ybIlV14J0g=
-go.opentelemetry.io/otel/metric v1.40.0 h1:rcZe317KPftE2rstWIBitCdVp89A2HqjkxR3c11+p9g=
-go.opentelemetry.io/otel/metric v1.40.0/go.mod h1:ib/crwQH7N3r5kfiBZQbwrTge743UDc7DTFVZrrXnqc=
-go.opentelemetry.io/otel/sdk v1.40.0 h1:KHW/jUzgo6wsPh9At46+h4upjtccTmuZCFAc9OJ71f8=
-go.opentelemetry.io/otel/sdk v1.40.0/go.mod h1:Ph7EFdYvxq72Y8Li9q8KebuYUr2KoeyHx0DRMKrYBUE=
-go.opentelemetry.io/otel/sdk/metric v1.40.0 h1:mtmdVqgQkeRxHgRv4qhyJduP3fYJRMX4AtAlbuWdCYw=
-go.opentelemetry.io/otel/sdk/metric v1.40.0/go.mod h1:4Z2bGMf0KSK3uRjlczMOeMhKU2rhUqdWNoKcYrtcBPg=
-go.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZYblVjw=
-go.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.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.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
-golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
-golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa h1:Zt3DZoOFFYkKhDT3v7Lm9FDMEV06GpzjG2jrqW+QTE0=
-golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
-golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
-golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
-golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
-golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
-golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
-golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
-golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
-golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
-golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
-golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
-gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
-gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
-google.golang.org/api v0.269.0 h1:qDrTOxKUQ/P0MveH6a7vZ+DNHxJQjtGm/uvdbdGXCQg=
-google.golang.org/api v0.269.0/go.mod h1:N8Wpcu23Tlccl0zSHEkcAZQKDLdquxK+l9r2LkwAauE=
-google.golang.org/genai v1.47.0 h1:iWCS7gEdO6rctOqfCYLOrZGKu2D+N42aTnCEcBvB1jo=
-google.golang.org/genai v1.47.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260223185530-2f722ef697dc h1:51Wupg8spF+5FC6D+iMKbOddFjMckETnNnEiZ+HX37s=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260223185530-2f722ef697dc/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.79.1 h1:zGhSi45ODB9/p3VAawt9a+O/MULLl9dpizzNNpq7flY=
-google.golang.org/grpc v1.79.1/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+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/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.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
+golang.org/x/sys v0.43.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/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
+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.52.1 h1:dYoljKtLDXMiBdVaClSJ/ZPwZ7j1N0lGjMhwOKOQUlk=
+google.golang.org/genai v1.52.1/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-20260406210006-6f92a3bedf2d h1:wT2n40TBqFY6wiwazVK9/iTWbsQrgk5ZfCSVFLO9LQA=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260406210006-6f92a3bedf2d/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

@@ -0,0 +1,470 @@
+// Package acpserver implements a Kit-backed ACP (Agent Client Protocol) agent.
+//
+// It bridges Kit's LLM execution, tool system, and session management to the
+// ACP protocol over stdio, allowing ACP clients (such as OpenCode) to drive
+// Kit as a remote coding agent.
+package acpserver
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"sync/atomic"
+
+	"github.com/charmbracelet/log"
+	acp "github.com/coder/acp-go-sdk"
+
+	kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+// Version is injected at build time; fallback to "dev".
+var Version = "dev"
+
+// execution, tool calls, and session management.
+type Agent struct {
+	conn     *acp.AgentSideConnection
+	registry *sessionRegistry
+
+	// toolCallCounter provides unique IDs for tool calls within a turn.
+	toolCallCounter atomic.Int64
+}
+
+// NewAgent creates a new ACP agent backed by Kit.
+func NewAgent() *Agent {
+	return &Agent{
+		registry: newSessionRegistry(),
+	}
+}
+
+// SetAgentConnection stores the connection so the agent can send session
+// updates (streaming, tool calls, etc.) back to the ACP client. This follows
+// the AgentConnAware duck-typing pattern from the SDK.
+func (a *Agent) SetAgentConnection(conn *acp.AgentSideConnection) {
+	a.conn = conn
+}
+
+// Close shuts down all active sessions.
+func (a *Agent) Close() {
+	a.registry.closeAll()
+}
+
+// ---------------------------------------------------------------------------
+// acp.Agent interface implementation
+// ---------------------------------------------------------------------------
+
+// Authenticate handles authentication requests. Kit doesn't require auth for
+// local stdio usage, so this is a no-op.
+func (a *Agent) Authenticate(_ context.Context, _ acp.AuthenticateRequest) (acp.AuthenticateResponse, error) {
+	return acp.AuthenticateResponse{}, nil
+}
+
+// Initialize negotiates capabilities with the ACP client.
+func (a *Agent) Initialize(_ context.Context, params acp.InitializeRequest) (acp.InitializeResponse, error) {
+	log.Debug("acp: initialize", "protocol_version", params.ProtocolVersion)
+
+	return acp.InitializeResponse{
+		ProtocolVersion: acp.ProtocolVersion(1),
+		AgentCapabilities: acp.AgentCapabilities{
+			LoadSession: true,
+			PromptCapabilities: acp.PromptCapabilities{
+				EmbeddedContext: true,
+				Image:           true,
+			},
+		},
+		AgentInfo: &acp.Implementation{
+			Name:    "Kit",
+			Version: Version,
+		},
+	}, nil
+}
+
+// NewSession creates a new Kit session for the given working directory.
+func (a *Agent) NewSession(ctx context.Context, params acp.NewSessionRequest) (acp.NewSessionResponse, error) {
+	cwd := params.Cwd
+	if cwd == "" {
+		return acp.NewSessionResponse{}, acp.NewInvalidParams("cwd is required")
+	}
+
+	log.Debug("acp: new_session", "cwd", cwd)
+
+	sess, err := a.registry.create(ctx, cwd)
+	if err != nil {
+		log.Error("acp: session creation failed", "cwd", cwd, "error", err)
+		return acp.NewSessionResponse{}, fmt.Errorf("create session: %w", err)
+	}
+
+	return acp.NewSessionResponse{
+		SessionId: acp.SessionId(sess.sessionID),
+	}, nil
+}
+
+// Prompt handles the main agent execution. It subscribes to Kit's event bus,
+// converts events to ACP session updates, and runs the prompt through Kit's
+// full turn lifecycle (hooks, LLM, tool calls, persistence).
+func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.PromptResponse, error) {
+	sessionID := string(params.SessionId)
+	sess, ok := a.registry.get(sessionID)
+	if !ok {
+		return acp.PromptResponse{}, acp.NewInvalidParams(
+			fmt.Sprintf("session not found: %s", sessionID),
+		)
+	}
+
+	// Extract text and file attachments from prompt content blocks.
+	promptText, files := extractPromptContent(params.Prompt)
+	if promptText == "" && len(files) == 0 {
+		return acp.PromptResponse{}, acp.NewInvalidParams("empty prompt")
+	}
+
+	// If we have files but no text prompt, add a default prompt
+	// This is required because the underlying LLM library needs a non-empty prompt
+	// when there are no previous messages in the conversation.
+	if promptText == "" && len(files) > 0 {
+		promptText = "Please analyze the attached file."
+	}
+
+	log.Debug("acp: prompt", "session", sessionID, "prompt_len", len(promptText), "files", len(files))
+
+	// Create a cancellable context for this prompt turn.
+	promptCtx, cancel := context.WithCancel(ctx)
+	sess.setCancel(cancel)
+	defer sess.clearCancel()
+
+	// Subscribe to Kit events and stream them as ACP session updates.
+	unsub := a.subscribeEvents(promptCtx, sess.kit, params.SessionId)
+	defer unsub()
+
+	// Run the prompt through Kit's full turn lifecycle.
+	// Use PromptResultWithFiles when file attachments are present.
+	var err error
+	if len(files) > 0 {
+		_, err = sess.kit.PromptResultWithFiles(promptCtx, promptText, files)
+	} else {
+		_, err = sess.kit.PromptResult(promptCtx, promptText)
+	}
+	if err != nil {
+		if promptCtx.Err() != nil {
+			return acp.PromptResponse{
+				StopReason: acp.StopReasonCancelled,
+			}, nil
+		}
+		return acp.PromptResponse{}, fmt.Errorf("prompt failed: %w", err)
+	}
+
+	return acp.PromptResponse{
+		StopReason: acp.StopReasonEndTurn,
+	}, nil
+}
+
+// Cancel cancels the ongoing prompt for a session.
+func (a *Agent) Cancel(_ context.Context, params acp.CancelNotification) error {
+	sessionID := string(params.SessionId)
+	sess, ok := a.registry.get(sessionID)
+	if !ok {
+		return nil // No-op if session doesn't exist.
+	}
+
+	log.Debug("acp: cancel", "session", sessionID)
+	sess.cancelPrompt()
+	return nil
+}
+
+// SetSessionMode is a no-op for now — Kit doesn't have built-in session modes.
+func (a *Agent) SetSessionMode(_ context.Context, _ acp.SetSessionModeRequest) (acp.SetSessionModeResponse, error) {
+	return acp.SetSessionModeResponse{}, nil
+}
+
+// SetSessionModel changes the active model for a session.
+func (a *Agent) SetSessionModel(ctx context.Context, params acp.SetSessionModelRequest) (acp.SetSessionModelResponse, error) {
+	sessionID := string(params.SessionId)
+	sess, ok := a.registry.get(sessionID)
+	if !ok {
+		return acp.SetSessionModelResponse{}, acp.NewInvalidParams(fmt.Sprintf("session not found: %s", sessionID))
+	}
+
+	modelID := string(params.ModelId)
+	log.Debug("acp: set_session_model", "session", sessionID, "model", modelID)
+
+	if err := sess.kit.SetModel(ctx, modelID); err != nil {
+		return acp.SetSessionModelResponse{}, fmt.Errorf("set model: %w", err)
+	}
+
+	return acp.SetSessionModelResponse{}, nil
+}
+
+// ---------------------------------------------------------------------------
+// Event streaming: Kit events → ACP SessionUpdate notifications
+// ---------------------------------------------------------------------------
+
+// subscribeEvents subscribes to Kit's event bus and forwards events as ACP
+// session update notifications to the client.
+func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.SessionId) func() {
+	return k.Subscribe(func(e kit.Event) {
+		// Don't send updates after the context is cancelled.
+		if ctx.Err() != nil {
+			return
+		}
+
+		var update *acp.SessionUpdate
+		switch ev := e.(type) {
+		case kit.MessageUpdateEvent:
+			u := acp.UpdateAgentMessageText(ev.Chunk)
+			update = &u
+
+		case kit.ReasoningDeltaEvent:
+			u := acp.UpdateAgentThoughtText(ev.Delta)
+			update = &u
+
+		case kit.ToolCallEvent:
+			tcID := acp.ToolCallId(ev.ToolCallID)
+			if tcID == "" {
+				tcID = acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Add(1)))
+			}
+			u := acp.StartToolCall(tcID, ev.ToolName,
+				acp.WithStartStatus(acp.ToolCallStatusInProgress),
+				acp.WithStartRawInput(parseToolArgs(ev.ToolArgs)),
+			)
+			update = &u
+
+		case kit.ToolResultEvent:
+			tcID := acp.ToolCallId(ev.ToolCallID)
+			if tcID == "" {
+				tcID = acp.ToolCallId(fmt.Sprintf("tc_%d", a.toolCallCounter.Load()))
+			}
+			status := acp.ToolCallStatusCompleted
+			if ev.IsError {
+				status = acp.ToolCallStatusFailed
+			}
+			u := acp.UpdateToolCall(tcID,
+				acp.WithUpdateStatus(status),
+				acp.WithUpdateContent([]acp.ToolCallContent{
+					acp.ToolContent(acp.TextBlock(ev.Result)),
+				}),
+			)
+			update = &u
+
+		case kit.ToolCallContentEvent:
+			u := acp.UpdateAgentMessageText(ev.Content)
+			update = &u
+		}
+
+		if update != nil {
+			_ = a.conn.SessionUpdate(ctx, acp.SessionNotification{
+				SessionId: sessionID,
+				Update:    *update,
+			})
+		}
+	})
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// extractPromptContent extracts text and file attachments from ACP content blocks.
+// It converts supported content blocks (image, audio, resource) to Kit's LLMFilePart.
+func extractPromptContent(blocks []acp.ContentBlock) (string, []kit.LLMFilePart) {
+	var textParts []string
+	var files []kit.LLMFilePart
+
+	log.Debug("acp: extracting content", "blocks", len(blocks))
+
+	for i, block := range blocks {
+		switch {
+		// Text content
+		case block.Text != nil:
+			log.Debug("acp: content block", "index", i, "type", "text", "len", len(block.Text.Text))
+			textParts = append(textParts, block.Text.Text)
+
+		// Image data (base64)
+		case block.Image != nil:
+			mimeType := block.Image.MimeType
+			if mimeType == "" {
+				mimeType = "image/png" // Default fallback
+			}
+			log.Debug("acp: content block", "index", i, "type", "image", "mime", mimeType, "data_len", len(block.Image.Data))
+			if data, err := base64.StdEncoding.DecodeString(block.Image.Data); err == nil {
+				files = append(files, kit.LLMFilePart{
+					Filename:  "image.png",
+					Data:      data,
+					MediaType: mimeType,
+				})
+			} else {
+				log.Debug("acp: failed to decode image", "error", err)
+			}
+
+		// Audio data (base64)
+		case block.Audio != nil:
+			mimeType := block.Audio.MimeType
+			if mimeType == "" {
+				mimeType = "audio/wav" // Default fallback
+			}
+			log.Debug("acp: content block", "index", i, "type", "audio", "mime", mimeType)
+			if data, err := base64.StdEncoding.DecodeString(block.Audio.Data); err == nil {
+				files = append(files, kit.LLMFilePart{
+					Filename:  "audio.wav",
+					Data:      data,
+					MediaType: mimeType,
+				})
+			} else {
+				log.Debug("acp: failed to decode audio", "error", err)
+			}
+
+		// Embedded resource (text or binary file content)
+		case block.Resource != nil:
+			log.Debug("acp: content block", "index", i, "type", "resource")
+			res := block.Resource.Resource
+			// Text resource - append as text content with file reference
+			if res.TextResourceContents != nil {
+				uri := res.TextResourceContents.Uri
+				content := res.TextResourceContents.Text
+				mimeType := "text/plain"
+				if res.TextResourceContents.MimeType != nil {
+					mimeType = *res.TextResourceContents.MimeType
+				}
+				log.Debug("acp: text resource", "uri", uri, "mime", mimeType, "len", len(content))
+				// Text files are included as formatted text, NOT as FilePart
+				// FilePart is for binary files (images, audio, PDFs) only
+				textParts = append(textParts, fmt.Sprintf("[File: %s]\n```\n%s\n```", uri, content))
+			}
+			// Binary resource (base64 blob) - these become FilePart
+			if res.BlobResourceContents != nil {
+				uri := res.BlobResourceContents.Uri
+				mimeType := "application/octet-stream"
+				if res.BlobResourceContents.MimeType != nil {
+					mimeType = *res.BlobResourceContents.MimeType
+				}
+				log.Debug("acp: binary resource", "uri", uri, "mime", mimeType, "blob_len", len(res.BlobResourceContents.Blob))
+				if data, err := base64.StdEncoding.DecodeString(res.BlobResourceContents.Blob); err == nil {
+					files = append(files, kit.LLMFilePart{
+						Filename:  extractFilenameFromURI(uri),
+						Data:      data,
+						MediaType: mimeType,
+					})
+				} else {
+					log.Debug("acp: failed to decode binary resource", "error", err)
+				}
+			}
+
+		// Resource link (file reference without embedded content)
+		case block.ResourceLink != nil:
+			uri := block.ResourceLink.Uri
+			name := block.ResourceLink.Name
+			log.Debug("acp: content block", "index", i, "type", "resource_link", "uri", uri, "name", name)
+			// For resource links, we'll try to read the file from disk
+			// This requires the file URI to be accessible (file:// scheme)
+			if content, err := readResourceFromURI(uri); err == nil {
+				// Detect if it's a text file or binary file
+				mimeType := "text/plain"
+				if block.ResourceLink.MimeType != nil {
+					mimeType = *block.ResourceLink.MimeType
+				}
+				log.Debug("acp: resource link loaded", "uri", uri, "mime", mimeType, "size", len(content))
+
+				// Only create FilePart for binary files (images, audio, PDFs, etc.)
+				// Text files are included as formatted text in the message
+				if isTextMimeType(mimeType) || looksLikeText(content) {
+					textParts = append(textParts, fmt.Sprintf("[File: %s]\n```\n%s\n```", uri, string(content)))
+				} else {
+					// Binary file - create FilePart for models that support it
+					files = append(files, kit.LLMFilePart{
+						Filename:  extractFilenameFromURI(uri),
+						Data:      content,
+						MediaType: mimeType,
+					})
+				}
+			} else {
+				// If we can't read it, include as a text reference
+				log.Debug("acp: resource link failed to load", "uri", uri, "error", err)
+				textParts = append(textParts, fmt.Sprintf("[Referenced file: %s]", uri))
+			}
+
+		default:
+			log.Debug("acp: content block", "index", i, "type", "unknown/unhandled")
+		}
+	}
+
+	// Debug log the extracted content
+	for i, f := range files {
+		log.Debug("acp: extracted file", "index", i, "filename", f.Filename, "mime", f.MediaType, "size", len(f.Data))
+	}
+
+	return strings.Join(textParts, "\n"), files
+}
+
+// isTextMimeType returns true if the MIME type indicates text content.
+func isTextMimeType(mimeType string) bool {
+	return strings.HasPrefix(mimeType, "text/") ||
+		mimeType == "application/json" ||
+		mimeType == "application/xml" ||
+		mimeType == "application/javascript" ||
+		mimeType == "application/typescript" ||
+		mimeType == "application/x-sh" ||
+		mimeType == "application/x-python" ||
+		mimeType == "application/x-yaml" ||
+		mimeType == "application/x-toml"
+}
+
+// looksLikeText checks if the content appears to be text (not binary).
+// It samples the first 512 bytes and checks for null bytes or high
+// concentration of non-printable characters.
+func looksLikeText(data []byte) bool {
+	if len(data) == 0 {
+		return true
+	}
+	// Check first 512 bytes (or less if file is smaller)
+	sampleSize := min(len(data), 512)
+	sample := data[:sampleSize]
+
+	// Count non-printable characters
+	nonPrintable := 0
+	for _, b := range sample {
+		// Null byte indicates binary
+		if b == 0 {
+			return false
+		}
+		// Count control characters (except common whitespace)
+		if b < 32 && b != '\n' && b != '\r' && b != '\t' {
+			nonPrintable++
+		}
+	}
+
+	// If more than 30% non-printable, consider it binary
+	return float64(nonPrintable)/float64(sampleSize) < 0.3
+}
+
+// extractFilenameFromURI extracts a filename from a file URI or path.
+func extractFilenameFromURI(uri string) string {
+	// Handle file:// URIs
+	uri = strings.TrimPrefix(uri, "file://")
+	// Extract basename
+	if idx := strings.LastIndex(uri, "/"); idx >= 0 {
+		return uri[idx+1:]
+	}
+	return uri
+}
+
+// readResourceFromURI attempts to read file content from a file:// URI.
+func readResourceFromURI(uri string) ([]byte, error) {
+	if !strings.HasPrefix(uri, "file://") {
+		return nil, fmt.Errorf("unsupported URI scheme: %s", uri)
+	}
+	path := uri[7:] // Remove file:// prefix
+	return os.ReadFile(path)
+}
+
+// parseToolArgs attempts to parse a JSON tool args string into a map for
+// structured display. Falls back to a simple string wrapper.
+func parseToolArgs(args string) any {
+	if args == "" {
+		return nil
+	}
+	var m map[string]any
+	if err := json.Unmarshal([]byte(args), &m); err == nil {
+		return m
+	}
+	return map[string]any{"input": args}
+}

internal/acpserver/session.go

@@ -0,0 +1,294 @@
+package acpserver
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/charmbracelet/log"
+
+	"github.com/mark3labs/kit/internal/extensions"
+	kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+// acpSession maps an ACP session to a Kit instance with its own tree session.
+type acpSession struct {
+	kit       *kit.Kit
+	cancelFn  context.CancelFunc // cancels the current prompt
+	cancelMu  sync.Mutex
+	cwd       string
+	sessionID string // Kit-generated session ID (from JSONL header)
+}
+
+// sessionRegistry is a thread-safe registry of ACP session ID → Kit sessions.
+type sessionRegistry struct {
+	mu       sync.RWMutex
+	sessions map[string]*acpSession // ACP session ID → session
+}
+
+func newSessionRegistry() *sessionRegistry {
+	return &sessionRegistry{
+		sessions: make(map[string]*acpSession),
+	}
+}
+
+// create creates a new Kit instance with a persisted tree session for the
+// given working directory. The Kit-generated session ID is used as the ACP
+// session ID so the mapping is 1:1.
+func (r *sessionRegistry) create(ctx context.Context, cwd string) (*acpSession, error) {
+	kitInstance, err := kit.New(ctx, &kit.Options{
+		SessionDir: cwd,
+		Quiet:      true,
+		Streaming:  true,
+	})
+	if err != nil {
+		// Provide actionable guidance for provider auth errors, which are
+		// the most common failure mode when running via ACP.
+		msg := err.Error()
+		if strings.Contains(msg, "API key") || strings.Contains(msg, "credentials") || strings.Contains(msg, "OAuth") {
+			return nil, fmt.Errorf("provider authentication failed: %w — run 'kit auth login <provider>' or set the appropriate environment variable before starting 'kit acp'", err)
+		}
+		return nil, fmt.Errorf("create kit instance: %w", err)
+	}
+
+	sessionID := kitInstance.GetSessionID()
+	if sessionID == "" {
+		_ = kitInstance.Close()
+		return nil, fmt.Errorf("kit instance has no session ID")
+	}
+
+	// Wire extension context with headless implementations so extensions
+	// work in ACP mode. TUI-dependent features (widgets, prompts, editor)
+	// become no-ops or return cancelled; all data/model/tool APIs work
+	// identically to interactive mode.
+	if kitInstance.Extensions().HasExtensions() {
+		kitInstance.Extensions().SetContext(extensions.Context{
+			SessionID:   sessionID,
+			CWD:         cwd,
+			Model:       kitInstance.GetModelString(),
+			Interactive: false,
+
+			// Output — route through structured logger.
+			Print:      func(text string) { log.Debug("extension: print", "text", text) },
+			PrintInfo:  func(text string) { log.Info("extension: info", "text", text) },
+			PrintError: func(text string) { log.Error("extension: error", "text", text) },
+			PrintBlock: func(opts extensions.PrintBlockOpts) {
+				log.Info("extension: block", "subtitle", opts.Subtitle, "text", opts.Text)
+			},
+
+			// Message injection — no-ops for now; ACP clients drive prompts.
+			SendMessage:   func(string) {},
+			CancelAndSend: func(string) {},
+			Exit:          func() {},
+
+			// TUI widgets/chrome — silent no-ops (no TUI in ACP).
+			SetWidget:       func(extensions.WidgetConfig) {},
+			RemoveWidget:    func(string) {},
+			SetHeader:       func(extensions.HeaderFooterConfig) {},
+			RemoveHeader:    func() {},
+			SetFooter:       func(extensions.HeaderFooterConfig) {},
+			RemoveFooter:    func() {},
+			SetEditor:       func(extensions.EditorConfig) {},
+			ResetEditor:     func() {},
+			SetEditorText:   func(string) {},
+			SetUIVisibility: func(extensions.UIVisibility) {},
+			SetStatus:       func(string, string, int) {},
+			RemoveStatus:    func(string) {},
+
+			// Interactive prompts — return cancelled (no user to prompt).
+			PromptSelect: func(extensions.PromptSelectConfig) extensions.PromptSelectResult {
+				return extensions.PromptSelectResult{Cancelled: true}
+			},
+			PromptConfirm: func(extensions.PromptConfirmConfig) extensions.PromptConfirmResult {
+				return extensions.PromptConfirmResult{Cancelled: true}
+			},
+			PromptInput: func(extensions.PromptInputConfig) extensions.PromptInputResult {
+				return extensions.PromptInputResult{Cancelled: true}
+			},
+			ShowOverlay: func(extensions.OverlayConfig) extensions.OverlayResult {
+				return extensions.OverlayResult{Cancelled: true, Index: -1}
+			},
+			SuspendTUI: func(callback func()) error { callback(); return nil },
+
+			// Data access — delegate to Kit instance.
+			GetContextStats: func() extensions.ContextStats {
+				s := kitInstance.GetContextStats()
+				return extensions.ContextStats{
+					EstimatedTokens: s.EstimatedTokens,
+					ContextLimit:    s.ContextLimit,
+					UsagePercent:    s.UsagePercent,
+					MessageCount:    s.MessageCount,
+				}
+			},
+			GetMessages:    func() []extensions.SessionMessage { return kitInstance.Extensions().GetSessionMessages() },
+			GetSessionPath: func() string { return kitInstance.GetSessionPath() },
+			AppendEntry: func(entryType, data string) (string, error) {
+				return kitInstance.Extensions().AppendEntry(entryType, data)
+			},
+			GetEntries: func(entryType string) []extensions.ExtensionEntry {
+				return kitInstance.Extensions().GetEntries(entryType)
+			},
+
+			// Options, model, and tool management.
+			GetOption: func(name string) string { return kitInstance.Extensions().GetOption(name) },
+			SetOption: func(name, value string) { kitInstance.Extensions().SetOption(name, value) },
+			SetModel: func(modelString string) error {
+				previousModel := kitInstance.Extensions().GetContext().Model
+				if err := kitInstance.SetModel(context.Background(), modelString); err != nil {
+					return err
+				}
+				kitInstance.Extensions().UpdateContextModel(modelString)
+				kitInstance.Extensions().EmitModelChange(modelString, previousModel, "extension")
+				return nil
+			},
+			GetAvailableModels: func() []extensions.ModelInfoEntry { return kitInstance.GetAvailableModels() },
+			EmitCustomEvent:    func(name, data string) { kitInstance.Extensions().EmitCustomEvent(name, data) },
+			GetAllTools:        func() []extensions.ToolInfo { return kitInstance.Extensions().GetToolInfos() },
+			SetActiveTools:     func(names []string) { kitInstance.Extensions().SetActiveTools(names) },
+
+			// LLM completions and subagents.
+			Complete: func(req extensions.CompleteRequest) (extensions.CompleteResponse, error) {
+				return kitInstance.ExecuteCompletion(context.Background(), req)
+			},
+			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
+				sdkCfg := kit.SubagentConfig{
+					Prompt:       config.Prompt,
+					Model:        config.Model,
+					SystemPrompt: config.SystemPrompt,
+					Timeout:      config.Timeout,
+					NoSession:    config.NoSession,
+				}
+				if config.OnEvent != nil {
+					sdkCfg.OnEvent = func(e kit.Event) {
+						se := sdkEventToSubagentEvent(e)
+						if se.Type != "" {
+							config.OnEvent(se)
+						}
+					}
+				}
+				result, err := kitInstance.Subagent(context.Background(), sdkCfg)
+				if result == nil {
+					return nil, &extensions.SubagentResult{Error: err}, err
+				}
+				extResult := &extensions.SubagentResult{
+					Response:  result.Response,
+					Error:     err,
+					SessionID: result.SessionID,
+					Elapsed:   result.Elapsed,
+				}
+				if result.Usage != nil {
+					extResult.Usage = &extensions.SubagentUsage{
+						InputTokens:  result.Usage.InputTokens,
+						OutputTokens: result.Usage.OutputTokens,
+					}
+				}
+				return nil, extResult, err
+			},
+
+			// Render — fall back to logging.
+			RenderMessage: func(name, content string) {
+				renderer := kitInstance.Extensions().GetMessageRenderer(name)
+				if renderer != nil && renderer.Render != nil {
+					content = renderer.Render(content, 80)
+				}
+				log.Info("extension: message", "renderer", name, "content", content)
+			},
+			ReloadExtensions: func() error { return kitInstance.Extensions().Reload() },
+		})
+		kitInstance.Extensions().EmitSessionStart()
+	}
+
+	sess := &acpSession{
+		kit:       kitInstance,
+		cwd:       cwd,
+		sessionID: sessionID,
+	}
+
+	r.mu.Lock()
+	r.sessions[sessionID] = sess
+	r.mu.Unlock()
+
+	return sess, nil
+}
+
+// get retrieves a session by ACP session ID.
+func (r *sessionRegistry) get(sessionID string) (*acpSession, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	s, ok := r.sessions[sessionID]
+	return s, ok
+}
+
+// closeAll closes all sessions.
+func (r *sessionRegistry) closeAll() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for id, sess := range r.sessions {
+		if sess.kit != nil {
+			_ = sess.kit.Close()
+		}
+		delete(r.sessions, id)
+	}
+}
+
+// cancelPrompt cancels the current prompt for a session, if any.
+func (s *acpSession) cancelPrompt() {
+	s.cancelMu.Lock()
+	defer s.cancelMu.Unlock()
+	if s.cancelFn != nil {
+		s.cancelFn()
+		s.cancelFn = nil
+	}
+}
+
+// setCancel stores a cancel function for the current prompt.
+func (s *acpSession) setCancel(cancel context.CancelFunc) {
+	s.cancelMu.Lock()
+	defer s.cancelMu.Unlock()
+	s.cancelFn = cancel
+}
+
+// clearCancel clears the stored cancel function (called when prompt completes).
+func (s *acpSession) clearCancel() {
+	s.cancelMu.Lock()
+	defer s.cancelMu.Unlock()
+	s.cancelFn = nil
+}
+
+// sdkEventToSubagentEvent converts an SDK event to an extension SubagentEvent.
+func sdkEventToSubagentEvent(e kit.Event) extensions.SubagentEvent {
+	switch ev := e.(type) {
+	case kit.MessageUpdateEvent:
+		return extensions.SubagentEvent{Type: "text", Content: ev.Chunk}
+	case kit.ReasoningDeltaEvent:
+		return extensions.SubagentEvent{Type: "reasoning", Content: ev.Delta}
+	case kit.ToolCallEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_call", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind, ToolArgs: ev.ToolArgs,
+		}
+	case kit.ToolExecutionStartEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_start", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolExecutionEndEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_execution_end", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+		}
+	case kit.ToolResultEvent:
+		return extensions.SubagentEvent{
+			Type: "tool_result", ToolCallID: ev.ToolCallID,
+			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
+			ToolResult: ev.Result, IsError: ev.IsError,
+		}
+	case kit.TurnStartEvent:
+		return extensions.SubagentEvent{Type: "turn_start"}
+	case kit.TurnEndEvent:
+		return extensions.SubagentEvent{Type: "turn_end"}
+	default:
+		return extensions.SubagentEvent{}
+	}
+}

internal/agent/agent.go

@@ -25,29 +25,51 @@ 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 Fantasy agent. Used by the extensions system
+	// before it is passed to the LLM agent. Used by the extensions system
 	// to intercept tool calls/results.
 	ToolWrapper func([]fantasy.AgentTool) []fantasy.AgentTool
 
 	// 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.
-type ToolCallHandler func(toolName, toolArgs string)
+type ToolCallHandler func(toolCallID, toolName, toolArgs string)
 
 // ToolExecutionHandler is a function type for handling tool execution start/end events.
-type ToolExecutionHandler func(toolName string, isStarting bool)
+type ToolExecutionHandler func(toolCallID, toolName, toolArgs string, isStarting bool)
 
 // ToolResultHandler is a function type for handling tool results.
-type ToolResultHandler func(toolName, toolArgs, result string, isError bool)
+// The metadata parameter carries optional structured data (e.g. file diff
+// info) from the tool execution, JSON-encoded. It may be empty.
+type ToolResultHandler func(toolCallID, toolName, toolArgs, result, metadata string, isError bool)
 
 // ResponseHandler is a function type for handling LLM responses.
 type ResponseHandler func(content string)
@@ -58,10 +80,41 @@ type StreamingResponseHandler func(content string)
 // ToolCallContentHandler is a function type for handling content that accompanies tool calls.
 type ToolCallContentHandler func(content string)
 
-// Agent represents an AI agent with core tool integration using the fantasy library.
+// 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
+// contains stderr output.
+// 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.
+type StepUsageHandler func(inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens int64)
+
+// Agent represents an AI agent with core tool integration using the LLM library.
 // Core tools (bash, read, write, edit, grep, find, ls) are registered as direct
-// fantasy.AgentTool implementations — no MCP layer, no serialization overhead.
+// 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
@@ -74,6 +127,25 @@ type Agent struct {
 	streamingEnabled bool
 	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.
@@ -82,52 +154,50 @@ type GenerateWithLoopResult struct {
 	FinalResponse *fantasy.Response
 	// ConversationMessages contains all messages in the conversation including tool calls and results
 	ConversationMessages []fantasy.Message
-	// Messages contains the conversation as custom content blocks (crush-style)
+	// Messages contains the conversation as custom content blocks
 	Messages []message.Message
 	// TotalUsage contains aggregate token usage across all steps
 	TotalUsage fantasy.Usage
+	// StopReason is the LLM provider's finish reason for the final response.
+	StopReason string
+	// 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 via fantasy
+	// Create the LLM provider
 	providerResult, err := models.CreateProvider(ctx, agentConfig.ModelConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create model provider: %v", err)
 	}
 
-	// Register core tools (direct fantasy implementations, no MCP overhead).
+	// 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...)
@@ -138,7 +208,150 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 		allTools = agentConfig.ToolWrapper(allTools)
 	}
 
-	// Build fantasy agent options
+	// 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()
+		toolManager.SetModel(providerResult.Model)
+		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, a.toolManager.GetTools()...)
+	}
+	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 != "" {
@@ -156,30 +369,35 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 		))
 	}
 
-	// Create the fantasy agent
-	fantasyAgent := fantasy.NewAgent(providerResult.Model, agentOpts...)
+	// Pass provider-specific options (e.g. OpenAI Responses API reasoning settings).
+	if providerResult.ProviderOptions != nil {
+		agentOpts = append(agentOpts, fantasy.WithProviderOptions(providerResult.ProviderOptions))
+	}
 
-	// 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
+	// Pass generation parameters when available.
+	if agentConfig.ModelConfig != nil {
+		// Skip max_output_tokens for providers that don't support it (e.g., Codex OAuth)
+		if agentConfig.ModelConfig.MaxTokens > 0 && !providerResult.SkipMaxOutputTokens {
+			agentOpts = append(agentOpts, fantasy.WithMaxOutputTokens(int64(agentConfig.ModelConfig.MaxTokens)))
+		}
+		if agentConfig.ModelConfig.Temperature != nil {
+			agentOpts = append(agentOpts, fantasy.WithTemperature(float64(*agentConfig.ModelConfig.Temperature)))
+		}
+		if agentConfig.ModelConfig.TopP != nil {
+			agentOpts = append(agentOpts, fantasy.WithTopP(float64(*agentConfig.ModelConfig.TopP)))
+		}
+		if agentConfig.ModelConfig.TopK != nil {
+			agentOpts = append(agentOpts, fantasy.WithTopK(int64(*agentConfig.ModelConfig.TopK)))
+		}
+		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,
-	}, nil
+	return agentOpts
 }
 
 // GenerateWithLoop processes messages with a custom loop that displays tool calls in real-time.
@@ -188,39 +406,92 @@ func (a *Agent) GenerateWithLoop(ctx context.Context, messages []fantasy.Message
 	onResponse ResponseHandler, onToolCallContent ToolCallContentHandler,
 ) (*GenerateWithLoopResult, error) {
 	return a.GenerateWithLoopAndStreaming(ctx, messages, onToolCall, onToolExecution, onToolResult,
-		onResponse, onToolCallContent, nil)
+		onResponse, onToolCallContent, nil, nil, nil, nil, nil, nil)
 }
 
-// GenerateWithLoopAndStreaming processes messages using the fantasy agent with streaming and callbacks.
-// Fantasy handles the tool call loop internally. We map fantasy's rich callback system
+// GenerateWithLoopAndStreaming processes messages using the agent with streaming and callbacks.
+// The agent handles the tool call loop internally. We map the rich callback system
 // to kit's existing callback interface for UI integration.
 func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fantasy.Message,
 	onToolCall ToolCallHandler, onToolExecution ToolExecutionHandler, onToolResult ToolResultHandler,
 	onResponse ResponseHandler, onToolCallContent ToolCallContentHandler,
 	onStreamingResponse StreamingResponseHandler,
+	onReasoningDelta ReasoningDeltaHandler,
+	onReasoningComplete ReasoningCompleteHandler,
+	onToolOutput ToolOutputHandler,
+	onStepMessages StepMessagesHandler,
+	onStepUsage StepUsageHandler,
 ) (*GenerateWithLoopResult, error) {
 
-	// Fantasy requires the current user input as Prompt, with prior messages as history.
-	// Extract the last user message text as the prompt, and pass everything before it as Messages.
-	prompt, history := splitPromptAndHistory(messages)
+	// 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()
 
-	// Track current tool call info for callbacks
-	var currentToolName string
+	// Inject tool output handler into context for use by core tools (e.g., bash).
+	if onToolOutput != nil {
+		ctx = core.ContextWithToolOutputCallback(ctx, onToolOutput)
+	}
+
+	// The agent requires the current user input as Prompt, with prior messages as history.
+	// Extract the last user message text and files as the prompt, and pass everything
+	// before it as Messages. Files (e.g. clipboard images) are passed via the Files
+	// field so the agent includes them in the API request.
+	prompt, files, history := splitPromptAndHistory(messages)
+
+	// Apply message-level cache control for Anthropic models.
+	// This avoids type conflicts with provider-level options.
+	history = applyCacheControlToMessages(history)
+
+	// Track current tool call args for callbacks
 	var currentToolArgs string
 
 	// Use the streaming path when streaming is enabled OR when any callbacks are
-	// provided. Fantasy only exposes tool/step callbacks on AgentStreamCall, so
+	// provided. The agent only exposes tool/step callbacks on AgentStreamCall, so
 	// Stream is required to observe tool execution in real time. The non-streaming
 	// Generate path is reserved for the simple case with no callbacks at all.
 	hasCallbacks := onToolCall != nil || onToolExecution != nil || onToolResult != nil ||
-		onToolCallContent != nil || onStreamingResponse != nil
+		onToolCallContent != nil || onStreamingResponse != nil || onReasoningDelta != nil
 
 	if a.streamingEnabled || hasCallbacks {
-		// Use fantasy's streaming agent
-		result, err := a.fantasyAgent.Stream(ctx, fantasy.AgentStreamCall{
+		// Track completed step messages so we can return partial results
+		// on cancellation. The agent's Stream() discards accumulated steps
+		// 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{
 			Prompt:   prompt,
+			Files:    files,
 			Messages: history,
 
+			// Reasoning/thinking streaming callback
+			OnReasoningDelta: func(id, delta string) error {
+				if ctx.Err() != nil {
+					return ctx.Err()
+				}
+				if onReasoningDelta != nil {
+					onReasoningDelta(delta)
+				}
+				return nil
+			},
+
+			// 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 {
@@ -237,17 +508,16 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				if ctx.Err() != nil {
 					return ctx.Err()
 				}
-				currentToolName = tc.ToolName
 				currentToolArgs = tc.Input
 
 				// Notify about the tool call
 				if onToolCall != nil {
-					onToolCall(tc.ToolName, tc.Input)
+					onToolCall(tc.ToolCallID, tc.ToolName, tc.Input)
 				}
 
 				// Notify tool execution starting
 				if onToolExecution != nil {
-					onToolExecution(tc.ToolName, true)
+					onToolExecution(tc.ToolCallID, tc.ToolName, tc.Input, true)
 				}
 
 				return nil
@@ -260,13 +530,13 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				}
 				// Notify tool execution finished
 				if onToolExecution != nil {
-					onToolExecution(tr.ToolName, false)
+					onToolExecution(tr.ToolCallID, tr.ToolName, currentToolArgs, false)
 				}
 
 				if onToolResult != nil {
 					// Extract result text and error status
 					resultText, isError := extractToolResultText(tr)
-					onToolResult(tr.ToolName, currentToolArgs, resultText, isError)
+					onToolResult(tr.ToolCallID, tr.ToolName, currentToolArgs, resultText, tr.ClientMetadata, isError)
 				}
 
 				return nil
@@ -274,6 +544,17 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 
 			// Step callbacks for content that accompanies tool calls
 			OnStepFinish: func(step fantasy.StepResult) error {
+				// Accumulate messages from completed steps so they can be
+				// 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()
 				}
@@ -283,66 +564,145 @@ func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fan
 				if text != "" && len(toolCalls) > 0 && onToolCallContent != nil {
 					onToolCallContent(text)
 				}
+				// Emit step usage for real-time cost tracking
+				if onStepUsage != nil {
+					onStepUsage(step.Usage.InputTokens, step.Usage.OutputTokens,
+						step.Usage.CacheReadTokens, step.Usage.CacheCreationTokens)
+				}
 				return nil
 			},
-		})
+		}
+
+		// If a steer channel is attached to the context, wire up a
+		// PrepareStep function that drains the channel between steps
+		// and injects pending steer messages as user messages before
+		// the next LLM call. This enables graceful mid-turn steering
+		// without cancelling in-progress tool execution.
+		if steerCh := steerChFromContext(ctx); steerCh != nil {
+			onConsumed := steerConsumedFromContext(ctx)
+			streamCall.PrepareStep = func(
+				stepCtx context.Context,
+				opts fantasy.PrepareStepFunctionOptions,
+			) (context.Context, fantasy.PrepareStepResult, error) {
+				// Drain all pending steer messages (non-blocking).
+				var steered []SteerMessage
+				for {
+					select {
+					case msg := <-steerCh:
+						steered = append(steered, msg)
+					default:
+						goto done
+					}
+				}
+			done:
+				result := fantasy.PrepareStepResult{
+					Model:    opts.Model,
+					Messages: opts.Messages,
+				}
+				if len(steered) > 0 {
+					// Inject each steer message as a user message so the
+					// LLM sees the redirection on the next step.
+					for _, sm := range steered {
+						result.Messages = append(result.Messages,
+							fantasy.NewUserMessage(sm.Text, sm.Files...))
+					}
+					// Notify that steer messages were consumed.
+					if onConsumed != nil {
+						onConsumed(len(steered))
+					}
+				}
+
+				// Apply message-level cache control for Anthropic models.
+				// This avoids type conflicts with provider-level options.
+				result.Messages = applyCacheControlToMessages(result.Messages)
+
+				return stepCtx, result, nil
+			}
+		}
+
+		result, err := a.fantasyAgent.Stream(ctx, streamCall)
 		if err != nil {
+			// On cancellation (or any error), return a partial result
+			// containing messages from completed steps so the caller can
+			// persist tool calls and results that finished before the
+			// cancellation. The original input messages are included so
+			// the caller sees the full conversation up to the point of
+			// cancellation.
+			if len(completedStepMessages) > 0 {
+				partialMessages := make([]fantasy.Message, 0, len(messages)+len(completedStepMessages))
+				partialMessages = append(partialMessages, messages...)
+				partialMessages = append(partialMessages, completedStepMessages...)
+				return &GenerateWithLoopResult{
+					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.
 	result, err := a.fantasyAgent.Generate(ctx, fantasy.AgentCall{
 		Prompt:   prompt,
+		Files:    files,
 		Messages: history,
 	})
 	if err != nil {
 		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())
 	}
 
-	_ = currentToolName // satisfy compiler for non-streaming path
-
 	return convertAgentResult(result, messages), nil
 }
 
 // splitPromptAndHistory extracts the last user message as the prompt string,
-// and returns everything before it as conversation history. Fantasy's agent
+// and returns everything before it as conversation history. The agent's
 // requires the current turn's input as Prompt (string), with prior messages
 // passed separately as Messages (history).
-func splitPromptAndHistory(messages []fantasy.Message) (string, []fantasy.Message) {
+func splitPromptAndHistory(messages []fantasy.Message) (string, []fantasy.FilePart, []fantasy.Message) {
 	if len(messages) == 0 {
-		return "", nil
+		return "", nil, nil
 	}
 
 	// Walk backwards to find the last user message
 	for i := len(messages) - 1; i >= 0; i-- {
 		if messages[i].Role == fantasy.MessageRoleUser {
-			// Extract text from the user message parts
+			// Extract text and file parts from the user message
 			var prompt string
+			var files []fantasy.FilePart
 			for _, part := range messages[i].Content {
-				if tp, ok := part.(fantasy.TextPart); ok {
-					prompt = tp.Text
-					break
+				switch p := part.(type) {
+				case fantasy.TextPart:
+					if prompt == "" {
+						prompt = p.Text
+					}
+				case fantasy.FilePart:
+					files = append(files, p)
 				}
 			}
 			// History is everything except this last user message
 			history := make([]fantasy.Message, 0, len(messages)-1)
 			history = append(history, messages[:i]...)
 			history = append(history, messages[i+1:]...)
-			return prompt, history
+			return prompt, files, history
 		}
 	}
 
@@ -350,15 +710,15 @@ func splitPromptAndHistory(messages []fantasy.Message) (string, []fantasy.Messag
 	last := messages[len(messages)-1]
 	for _, part := range last.Content {
 		if tp, ok := part.(fantasy.TextPart); ok {
-			return tp.Text, messages[:len(messages)-1]
+			return tp.Text, nil, messages[:len(messages)-1]
 		}
 	}
 
-	return "", messages
+	return "", nil, messages
 }
 
-// convertAgentResult converts a fantasy AgentResult to our GenerateWithLoopResult.
-// It builds both the legacy fantasy.Message slice and the new custom content blocks.
+// convertAgentResult converts an AgentResult to our GenerateWithLoopResult.
+// It builds both the message slice and the new custom content blocks.
 func convertAgentResult(result *fantasy.AgentResult, originalMessages []fantasy.Message) *GenerateWithLoopResult {
 	// Collect all conversation messages: original + all step messages
 	var allFantasyMessages []fantasy.Message
@@ -371,7 +731,7 @@ func convertAgentResult(result *fantasy.AgentResult, originalMessages []fantasy.
 	// Convert to custom content blocks
 	var allMessages []message.Message
 	for _, fm := range allFantasyMessages {
-		allMessages = append(allMessages, message.FromFantasyMessage(fm))
+		allMessages = append(allMessages, message.FromLLMMessage(fm))
 	}
 
 	return &GenerateWithLoopResult{
@@ -379,10 +739,11 @@ func convertAgentResult(result *fantasy.AgentResult, originalMessages []fantasy.
 		ConversationMessages: allFantasyMessages,
 		Messages:             allMessages,
 		TotalUsage:           result.TotalUsage,
+		StopReason:           string(result.Response.FinishReason),
 	}
 }
 
-// extractToolResultText extracts the text and error status from a fantasy ToolResultContent.
+// extractToolResultText extracts the text and error status from a ToolResultContent.
 // For core tools, the result is already clean text (no MCP JSON wrapping).
 // For MCP tools, it unwraps the MCP content structure.
 func extractToolResultText(tr fantasy.ToolResultContent) (string, bool) {
@@ -395,7 +756,7 @@ func extractToolResultText(tr fantasy.ToolResultContent) (string, bool) {
 		return errResult.Error.Error(), true
 	}
 
-	// Get text directly from the Fantasy result type.
+	// Get text directly from the result type.
 	if textResult, ok := tr.Result.(fantasy.ToolResultOutputContentText); ok {
 		// Try to unwrap MCP JSON structure (for external MCP tools).
 		// Core tools return plain text, so this is a no-op for them.
@@ -455,6 +816,11 @@ func (a *Agent) GetTools() []fantasy.AgentTool {
 	return allTools
 }
 
+// GetCoreToolCount returns the number of core tools.
+func (a *Agent) GetCoreToolCount() int {
+	return len(a.coreTools)
+}
+
 // GetMCPToolCount returns the number of tools loaded from external MCP servers.
 func (a *Agent) GetMCPToolCount() int {
 	if a.toolManager == nil {
@@ -468,6 +834,73 @@ 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()
+		a.toolManager.SetModel(a.model)
+		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
@@ -481,13 +914,70 @@ func (a *Agent) GetLoadedServerNames() []string {
 	return a.toolManager.GetLoadedServerNames()
 }
 
-// GetModel returns the underlying fantasy LanguageModel.
+// 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)
+	}
+	// 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.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 != "" {
+		if p, _, err := models.ParseModelString(config.ModelString); err == nil {
+			a.providerType = p
+		}
+	}
+
+	// Rebuild the fantasy agent with the new model and current tool set.
+	a.rebuildFantasyAgent()
+
+	return nil
+}
+
+// GetModel returns the underlying LanguageModel.
 func (a *Agent) GetModel() fantasy.LanguageModel {
 	return a.model
 }
 
 // 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/cache_control.go

@@ -0,0 +1,84 @@
+package agent
+
+import (
+	"charm.land/fantasy"
+	"charm.land/fantasy/providers/anthropic"
+)
+
+// cacheControlOptions returns provider options for Anthropic cache control.
+// This is used at the message level to avoid type conflicts with provider-level options.
+func cacheControlOptions() fantasy.ProviderOptions {
+	return anthropic.NewProviderCacheControlOptions(&anthropic.ProviderCacheControlOptions{
+		CacheControl: anthropic.CacheControl{
+			Type: "ephemeral",
+		},
+	})
+}
+
+// applyCacheControlToMessages adds cache control to specific messages.
+// Anthropic allows max 4 cache blocks per request.
+// Counts existing cache blocks and only adds new ones up to the limit.
+func applyCacheControlToMessages(messages []fantasy.Message) []fantasy.Message {
+	if len(messages) == 0 {
+		return messages
+	}
+
+	// Make a copy to avoid modifying the original slice
+	result := make([]fantasy.Message, len(messages))
+	copy(result, messages)
+
+	cacheOpts := cacheControlOptions()
+	maxCacheBlocks := 4
+
+	// Helper to check if message already has cache control
+	hasCache := func(msg fantasy.Message) bool {
+		if msg.ProviderOptions == nil {
+			return false
+		}
+		if _, ok := msg.ProviderOptions["anthropic"]; ok {
+			return true
+		}
+		return false
+	}
+
+	// Count existing cache blocks
+	existingCacheCount := 0
+	for _, msg := range result {
+		if hasCache(msg) {
+			existingCacheCount++
+		}
+	}
+
+	// If we're already at or over the limit, don't add more
+	if existingCacheCount >= maxCacheBlocks {
+		return result
+	}
+
+	// How many new cache blocks can we add?
+	remaining := maxCacheBlocks - existingCacheCount
+
+	// First: find and cache the last system message (most important)
+	lastSystemIdx := -1
+	for i, msg := range result {
+		if msg.Role == fantasy.MessageRoleSystem {
+			lastSystemIdx = i
+		}
+	}
+
+	if lastSystemIdx >= 0 && remaining > 0 && !hasCache(result[lastSystemIdx]) {
+		result[lastSystemIdx].ProviderOptions = cacheOpts
+		remaining--
+	}
+
+	// Second: cache the most recent messages (up to remaining limit)
+	// Work backwards from the end to prioritize recent context
+	for i := len(result) - 1; i >= 0 && remaining > 0; i-- {
+		if hasCache(result[i]) {
+			continue
+		}
+		result[i].ProviderOptions = cacheOpts
+		remaining--
+	}
+
+	return result
+}

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
-	// ToolWrapper wraps the combined tool list before Fantasy agent creation.
+	// 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/steer.go

@@ -0,0 +1,46 @@
+package agent
+
+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{}
+
+// steerConsumedKey is the context key for the steer-consumed callback.
+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 SteerMessage) context.Context {
+	return context.WithValue(ctx, steerChKey{}, ch)
+}
+
+// ContextWithSteerConsumed returns a new context with a callback that fires
+// when steer messages are consumed by PrepareStep. The count argument is the
+// number of messages injected in this batch.
+func ContextWithSteerConsumed(ctx context.Context, fn func(count int)) context.Context {
+	return context.WithValue(ctx, steerConsumedKey{}, fn)
+}
+
+// steerChFromContext extracts the steer channel from the context, or nil.
+func steerChFromContext(ctx context.Context) <-chan SteerMessage {
+	ch, _ := ctx.Value(steerChKey{}).(<-chan SteerMessage)
+	return ch
+}
+
+// steerConsumedFromContext extracts the steer-consumed callback, or nil.
+func steerConsumedFromContext(ctx context.Context) func(int) {
+	fn, _ := ctx.Value(steerConsumedKey{}).(func(int))
+	return fn
+}

internal/app/app_test.go

@@ -14,6 +14,47 @@ import (
 // Helpers
 // --------------------------------------------------------------------------
 
+type usageUpdaterStub struct {
+	mu sync.Mutex
+
+	updateCalls   int
+	estimateCalls int
+	contextCalls  int
+
+	lastUpdateInput      int
+	lastUpdateOutput     int
+	lastUpdateCacheRead  int
+	lastUpdateCacheWrite int
+	lastContextTokens    int
+	lastEstimateInput    string
+	lastEstimateOutput   string
+}
+
+func (s *usageUpdaterStub) UpdateUsage(inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens int) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.updateCalls++
+	s.lastUpdateInput = inputTokens
+	s.lastUpdateOutput = outputTokens
+	s.lastUpdateCacheRead = cacheReadTokens
+	s.lastUpdateCacheWrite = cacheWriteTokens
+}
+
+func (s *usageUpdaterStub) EstimateAndUpdateUsage(inputText, outputText string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.estimateCalls++
+	s.lastEstimateInput = inputText
+	s.lastEstimateOutput = outputText
+}
+
+func (s *usageUpdaterStub) SetContextTokens(tokens int) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.contextCalls++
+	s.lastContextTokens = tokens
+}
+
 // turnResult builds a minimal TurnResult with response text t.
 func turnResult(t string) *kit.TurnResult {
 	return &kit.TurnResult{Response: t}
@@ -120,9 +161,8 @@ func TestRun_single(t *testing.T) {
 // Run (queued prompts)
 // --------------------------------------------------------------------------
 
-// TestRun_queued verifies that a second Run() call while the first is in-flight
-// enqueues the prompt rather than spawning a second goroutine, and that the
-// queue is drained after the first step completes.
+// TestRun_queued verifies that queued prompts are batched together and submitted
+// as a single agent turn rather than individually.
 func TestRun_queued(t *testing.T) {
 	gate := make(chan struct{})
 	callCount := 0
@@ -134,13 +174,7 @@ func TestRun_queued(t *testing.T) {
 			callCount++
 			mu.Unlock()
 			<-gate
-			return turnResult("first"), nil
-		},
-		func(_ context.Context) (*kit.TurnResult, error) {
-			mu.Lock()
-			callCount++
-			mu.Unlock()
-			return turnResult("second"), nil
+			return turnResult("batch result"), nil
 		},
 	)
 	app := newTestApp(stub)
@@ -165,11 +199,15 @@ func TestRun_queued(t *testing.T) {
 		t.Fatal("app did not become idle within 3s after queued runs")
 	}
 
+	// Wait for the goroutine to fully finish (avoid race with queue check)
+	app.wg.Wait()
+
 	mu.Lock()
 	total := callCount
 	mu.Unlock()
-	if total != 2 {
-		t.Fatalf("expected 2 calls, got %d", total)
+	// With batching, both prompts should be processed in a single call
+	if total != 1 {
+		t.Fatalf("expected 1 batched call, got %d", total)
 	}
 	if got := app.QueueLength(); got != 0 {
 		t.Fatalf("expected empty queue after drain, got %d", got)
@@ -180,31 +218,22 @@ func TestRun_queued(t *testing.T) {
 // Queue drain ordering
 // --------------------------------------------------------------------------
 
-// TestQueueDrainOrdering verifies that queued prompts are consumed in FIFO order.
+// TestQueueDrainOrdering verifies that queued prompts are batched together and
+// processed in a single agent turn.
 func TestQueueDrainOrdering(t *testing.T) {
 	gate := make(chan struct{})
-	var order []string
+	var receivedPrompt string
 	var mu sync.Mutex
 
 	stub := newStubWithFuncs(
 		func(ctx context.Context) (*kit.TurnResult, error) {
 			mu.Lock()
-			order = append(order, "first")
+			// In test mode with PromptFunc, we receive the first prompt
+			// but all messages are batched together
+			receivedPrompt = "batched"
 			mu.Unlock()
 			<-gate
-			return turnResult("first"), nil
-		},
-		func(_ context.Context) (*kit.TurnResult, error) {
-			mu.Lock()
-			order = append(order, "second")
-			mu.Unlock()
-			return turnResult("second"), nil
-		},
-		func(_ context.Context) (*kit.TurnResult, error) {
-			mu.Lock()
-			order = append(order, "third")
-			mu.Unlock()
-			return turnResult("third"), nil
+			return turnResult("batch result"), nil
 		},
 	)
 
@@ -228,16 +257,12 @@ func TestQueueDrainOrdering(t *testing.T) {
 	}
 
 	mu.Lock()
-	got := order
+	got := receivedPrompt
 	mu.Unlock()
 
-	if len(got) != 3 {
-		t.Fatalf("expected 3 calls, got %d: %v", len(got), got)
-	}
-	for i, want := range []string{"first", "second", "third"} {
-		if got[i] != want {
-			t.Fatalf("call[%d]: expected %q, got %q", i, want, got[i])
-		}
+	// With batching, all 3 prompts should be processed in a single call
+	if got != "batched" {
+		t.Fatalf("expected batched processing, got %q", got)
 	}
 }
 
@@ -494,10 +519,150 @@ func TestQueueLength_reflects(t *testing.T) {
 	}
 
 	app.mu.Lock()
-	app.queue = append(app.queue, "a", "b", "c")
+	app.queue = append(app.queue,
+		queueItem{Prompt: "a"},
+		queueItem{Prompt: "b"},
+		queueItem{Prompt: "c"},
+	)
 	app.mu.Unlock()
 
 	if got := app.QueueLength(); got != 3 {
 		t.Fatalf("expected 3, got %d", got)
 	}
 }
+
+// TestRecordStepUsage_updatesTracker verifies that per-step usage updates are
+// recorded immediately for cost tracking. Context tokens are NOT updated here
+// (only via updateUsageFromTurnResult) to avoid display jumps during multi-step
+// tool calls.
+func TestRecordStepUsage_updatesTracker(t *testing.T) {
+	usage := &usageUpdaterStub{}
+	app := New(Options{UsageTracker: usage}, nil)
+	defer app.Close()
+
+	app.recordStepUsage(kit.StepUsageEvent{
+		InputTokens:      120,
+		OutputTokens:     45,
+		CacheReadTokens:  5,
+		CacheWriteTokens: 2,
+	}, nil)
+
+	usage.mu.Lock()
+	defer usage.mu.Unlock()
+
+	if usage.updateCalls != 1 {
+		t.Fatalf("expected 1 update call, got %d", usage.updateCalls)
+	}
+	if usage.lastUpdateInput != 120 || usage.lastUpdateOutput != 45 || usage.lastUpdateCacheRead != 5 || usage.lastUpdateCacheWrite != 2 {
+		t.Fatalf("unexpected usage update payload: in=%d out=%d cache_read=%d cache_write=%d",
+			usage.lastUpdateInput, usage.lastUpdateOutput, usage.lastUpdateCacheRead, usage.lastUpdateCacheWrite)
+	}
+	// Context tokens should NOT be updated by recordStepUsage (only by updateUsageFromTurnResult)
+	if usage.contextCalls != 0 {
+		t.Fatalf("expected 0 context token updates from recordStepUsage, got %d", usage.contextCalls)
+	}
+}
+
+// TestUpdateUsageFromTurnResult_skipsTotalsWhenStepUsageSeen ensures we avoid
+// double-counting totals once StepUsageEvent-based updates were already applied.
+func TestUpdateUsageFromTurnResult_skipsTotalsWhenStepUsageSeen(t *testing.T) {
+	usage := &usageUpdaterStub{}
+	app := New(Options{UsageTracker: usage}, nil)
+	defer app.Close()
+
+	app.updateUsageFromTurnResult(&kit.TurnResult{
+		Response: "ok",
+		TotalUsage: &kit.LLMUsage{
+			InputTokens:         999,
+			OutputTokens:        111,
+			CacheReadTokens:     7,
+			CacheCreationTokens: 3,
+		},
+		FinalUsage: &kit.LLMUsage{InputTokens: 456},
+	}, "prompt", true)
+
+	usage.mu.Lock()
+	defer usage.mu.Unlock()
+
+	if usage.updateCalls != 0 {
+		t.Fatalf("expected no total usage update when sawStepUsage=true, got %d", usage.updateCalls)
+	}
+	if usage.estimateCalls != 0 {
+		t.Fatalf("expected no estimate update when sawStepUsage=true, got %d", usage.estimateCalls)
+	}
+	// Context tokens should be InputTokens only (456)
+	if usage.contextCalls != 1 || usage.lastContextTokens != 456 {
+		t.Fatalf("expected final context tokens=456 (InputTokens only), got calls=%d tokens=%d", usage.contextCalls, usage.lastContextTokens)
+	}
+}
+
+// TestUpdateUsageFromTurnResult_recordsWhenInputTokensZero verifies that usage
+// is recorded when InputTokens=0 but OutputTokens>0 (OpenAI-compatible cache behavior).
+func TestUpdateUsageFromTurnResult_recordsWhenInputTokensZero(t *testing.T) {
+	usage := &usageUpdaterStub{}
+	app := New(Options{UsageTracker: usage}, nil)
+	defer app.Close()
+
+	// Simulate OpenAI-compatible behavior: all prompt tokens cached, InputTokens=0
+	app.updateUsageFromTurnResult(&kit.TurnResult{
+		Response: "ok",
+		TotalUsage: &kit.LLMUsage{
+			InputTokens:         0,   // All cached - subtracted from prompt
+			OutputTokens:        150, // Actual generated tokens
+			CacheReadTokens:     500, // Cache hit
+			CacheCreationTokens: 0,
+		},
+		FinalUsage: &kit.LLMUsage{InputTokens: 0, OutputTokens: 150},
+	}, "prompt", false)
+
+	usage.mu.Lock()
+	defer usage.mu.Unlock()
+
+	if usage.updateCalls != 1 {
+		t.Fatalf("expected 1 update call when InputTokens=0 but OutputTokens>0, got %d", usage.updateCalls)
+	}
+	if usage.lastUpdateInput != 0 || usage.lastUpdateOutput != 150 {
+		t.Fatalf("expected input=0 output=150, got input=%d output=%d",
+			usage.lastUpdateInput, usage.lastUpdateOutput)
+	}
+	if usage.lastUpdateCacheRead != 500 {
+		t.Fatalf("expected cache_read=500, got %d", usage.lastUpdateCacheRead)
+	}
+}
+
+// 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()
+
+	app.updateUsageFromTurnResult(&kit.TurnResult{
+		Response: "ok",
+		TotalUsage: &kit.LLMUsage{
+			InputTokens:         3,
+			OutputTokens:        5,
+			CacheReadTokens:     0,
+			CacheCreationTokens: 4317,
+		},
+		FinalUsage: &kit.LLMUsage{
+			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 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

@@ -1,6 +1,6 @@
 package app
 
-import "charm.land/fantasy"
+import kit "github.com/mark3labs/kit/pkg/kit"
 
 // StreamChunkEvent is sent by the app layer when a streaming text delta arrives
 // from the LLM. Each chunk contains an incremental portion of the response.
@@ -9,9 +9,23 @@ type StreamChunkEvent struct {
 	Content string
 }
 
+// ReasoningChunkEvent is sent when a streaming reasoning/thinking delta arrives
+// from the LLM. Thinking content is rendered separately from regular text.
+type ReasoningChunkEvent struct {
+	// Delta is the incremental reasoning text from the streaming response.
+	Delta string
+}
+
+// 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 {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool being called.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments for the tool call.
@@ -21,14 +35,20 @@ type ToolCallStartedEvent struct {
 // ToolExecutionEvent is sent when a tool starts or finishes executing.
 // The IsStarting flag distinguishes between the start and end of execution.
 type ToolExecutionEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool being executed.
 	ToolName string
+	// ToolArgs is the JSON-encoded arguments for the tool call (only set when IsStarting is true).
+	ToolArgs string
 	// IsStarting is true when execution is beginning, false when it is complete.
 	IsStarting bool
 }
 
 // ToolResultEvent is sent after a tool execution completes with its result.
 type ToolResultEvent struct {
+	// ToolCallID is the stable identifier for correlating tool lifecycle events.
+	ToolCallID string
 	// ToolName is the name of the tool that was executed.
 	ToolName string
 	// ToolArgs is the JSON-encoded arguments that were passed to the tool.
@@ -39,6 +59,19 @@ type ToolResultEvent struct {
 	IsError bool
 }
 
+// ToolOutputEvent is sent when a tool produces streaming output chunks (e.g., bash output).
+// This allows the TUI to display tool output as it arrives, before the tool completes.
+type ToolOutputEvent struct {
+	// ToolCallID is the stable identifier for the tool call producing output.
+	ToolCallID string
+	// ToolName is the name of the tool producing output.
+	ToolName string
+	// Chunk is a piece of the tool's output text.
+	Chunk string
+	// IsStderr indicates whether this chunk came from stderr.
+	IsStderr bool
+}
+
 // ToolCallContentEvent is sent when a step includes text content alongside tool calls.
 // This allows the TUI to display assistant commentary that accompanies tool usage.
 type ToolCallContentEvent struct {
@@ -90,8 +123,8 @@ type SpinnerEvent struct {
 // MessageCreatedEvent is sent when a new message is added to the message store.
 // This allows the TUI to stay in sync with the conversation history.
 type MessageCreatedEvent struct {
-	// Message is the fantasy message that was added to the store.
-	Message fantasy.Message
+	// Message is the message that was added to the store.
+	Message kit.LLMMessage
 }
 
 // CompactCompleteEvent is sent when a /compact operation finishes successfully.
@@ -113,6 +146,53 @@ type CompactErrorEvent struct {
 	Err error
 }
 
+// SteerConsumedEvent is sent when one or more steering messages have been
+// consumed — either injected mid-turn via PrepareStep, or drained into the
+// queue after a turn completes. The TUI uses this to clear the steering
+// badge from the display.
+type SteerConsumedEvent struct{}
+
+// ModelChangedEvent is sent when an extension changes the active model via
+// ctx.SetModel. The TUI updates the model name shown in the status bar and
+// message attribution.
+type ModelChangedEvent struct {
+	// ProviderName is the new provider (e.g. "anthropic").
+	ProviderName string
+	// ModelName is the new model ID (e.g. "claude-3-5-haiku-20241022").
+	ModelName string
+}
+
+// WidgetUpdateEvent is sent when an extension adds, updates, or removes a
+// widget via ctx.SetWidget or ctx.RemoveWidget. The TUI re-reads widget state
+// 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.
+type EditorTextSetEvent struct {
+	Text string
+}
+
 // ExtensionPrintEvent is sent when an extension calls ctx.Print, ctx.PrintInfo,
 // ctx.PrintError, or ctx.PrintBlock. The TUI renders it via the appropriate
 // renderer and tea.Println (scrollback); the CLI handler uses
@@ -132,3 +212,89 @@ type ExtensionPrintEvent struct {
 	// Subtitle is optional muted text below the content for Level="block".
 	Subtitle string
 }
+
+// PromptResponse carries the user's answer to an interactive prompt. The TUI
+// sends exactly one PromptResponse through the channel embedded in
+// PromptRequestEvent when the user completes or cancels the prompt.
+type PromptResponse struct {
+	// Value is the response text — the selected option (select), or the
+	// entered text (input). Unused for confirm prompts.
+	Value string
+	// Index is the zero-based index of the selected option (select only).
+	Index int
+	// Confirmed is the boolean answer for confirm prompts.
+	Confirmed bool
+	// Cancelled is true if the user dismissed the prompt (ESC) or the
+	// prompt could not be shown (e.g. app shutting down).
+	Cancelled bool
+}
+
+// PromptRequestEvent is sent when an extension requests an interactive
+// prompt from the user (select, confirm, or text input). The TUI enters a
+// modal prompt state, renders the prompt, and sends a single PromptResponse
+// through ResponseCh when the user completes or cancels.
+//
+// The extension goroutine blocks on the read side of ResponseCh until the
+// TUI sends a response. The channel must have buffer size >= 1.
+type PromptRequestEvent struct {
+	// PromptType is "select", "confirm", or "input".
+	PromptType string
+	// Message is the question displayed to the user.
+	Message string
+	// Options lists the choices for select prompts.
+	Options []string
+	// Default is the pre-filled value: "true"/"false" for confirm prompts,
+	// or the initial text for input prompts.
+	Default string
+	// Placeholder is the ghost text for input prompts.
+	Placeholder string
+	// ResponseCh receives the user's answer. The TUI must send exactly one
+	// value. The channel must be buffered (cap >= 1) so sending never
+	// blocks inside Update().
+	ResponseCh chan<- PromptResponse
+}
+
+// OverlayResponse carries the user's answer to a modal overlay dialog. The
+// TUI sends exactly one OverlayResponse through the channel embedded in
+// OverlayRequestEvent when the user completes or cancels the overlay.
+type OverlayResponse struct {
+	// Action is the text of the selected action button, or "" if no actions
+	// were configured or the dialog was dismissed without selection.
+	Action string
+	// Index is the zero-based index of the selected action, or -1 if no
+	// action was selected.
+	Index int
+	// Cancelled is true if the user dismissed the overlay (ESC) or the
+	// overlay could not be shown (e.g. non-interactive mode).
+	Cancelled bool
+}
+
+// OverlayRequestEvent is sent when an extension requests a modal overlay
+// dialog. The TUI enters an overlay state, renders the dialog, and sends a
+// single OverlayResponse through ResponseCh when the user dismisses or
+// selects an action.
+//
+// The extension goroutine blocks on the read side of ResponseCh until the
+// TUI sends a response. The channel must have buffer size >= 1.
+type OverlayRequestEvent struct {
+	// Title is displayed at the top of the dialog. Empty means no title.
+	Title string
+	// Content is the text to render inside the dialog body.
+	Content string
+	// Markdown, when true, renders Content as styled markdown.
+	Markdown bool
+	// BorderColor is a hex color for the dialog border. Empty uses default.
+	BorderColor string
+	// Background is a hex color for the dialog background. Empty = none.
+	Background string
+	// Width is the dialog width in columns. 0 = auto (60% of terminal).
+	Width int
+	// MaxHeight limits dialog height. 0 = auto (80% of terminal).
+	MaxHeight int
+	// Anchor is the vertical positioning: "center", "top-center", "bottom-center".
+	Anchor string
+	// Actions lists the action button labels. Empty = simple dismiss dialog.
+	Actions []string
+	// ResponseCh receives the user's response. Must have buffer size >= 1.
+	ResponseCh chan<- OverlayResponse
+}

internal/app/messages.go

@@ -3,14 +3,14 @@ package app
 import (
 	"sync"
 
-	"charm.land/fantasy"
+	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
 // MessageStore is a thread-safe in-memory store for the conversation history.
 // On-disk persistence is handled by the TreeManager at the app/SDK layer.
 type MessageStore struct {
 	mu       sync.RWMutex
-	messages []fantasy.Message
+	messages []kit.LLMMessage
 }
 
 // NewMessageStore creates an empty MessageStore.
@@ -20,14 +20,14 @@ func NewMessageStore() *MessageStore {
 
 // NewMessageStoreWithMessages creates a MessageStore pre-populated with the
 // given messages. This is used when loading an existing session at startup.
-func NewMessageStoreWithMessages(msgs []fantasy.Message) *MessageStore {
-	cp := make([]fantasy.Message, len(msgs))
+func NewMessageStoreWithMessages(msgs []kit.LLMMessage) *MessageStore {
+	cp := make([]kit.LLMMessage, len(msgs))
 	copy(cp, msgs)
 	return &MessageStore{messages: cp}
 }
 
 // Add appends a single message to the store.
-func (s *MessageStore) Add(msg fantasy.Message) {
+func (s *MessageStore) Add(msg kit.LLMMessage) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	s.messages = append(s.messages, msg)
@@ -36,22 +36,22 @@ func (s *MessageStore) Add(msg fantasy.Message) {
 // Replace replaces the entire message history with the given slice. This is
 // used after an agent step returns the full updated conversation (including
 // tool calls and results).
-func (s *MessageStore) Replace(msgs []fantasy.Message) {
+func (s *MessageStore) Replace(msgs []kit.LLMMessage) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
-	cp := make([]fantasy.Message, len(msgs))
+	cp := make([]kit.LLMMessage, len(msgs))
 	copy(cp, msgs)
 	s.messages = cp
 }
 
 // GetAll returns a snapshot copy of the current message slice.
 // The returned slice is safe to modify without affecting the store.
-func (s *MessageStore) GetAll() []fantasy.Message {
+func (s *MessageStore) GetAll() []kit.LLMMessage {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	cp := make([]fantasy.Message, len(s.messages))
+	cp := make([]kit.LLMMessage, len(s.messages))
 	copy(cp, s.messages)
 	return cp
 }

internal/app/messages_test.go

@@ -4,16 +4,29 @@ import (
 	"testing"
 
 	"charm.land/fantasy"
+
+	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
-// makeTextMsg builds a minimal fantasy.Message with a single TextPart.
-func makeTextMsg(role, text string) fantasy.Message {
-	return fantasy.Message{
-		Role:    fantasy.MessageRole(role),
+// makeTextMsg builds a minimal kit.LLMMessage using fantasy.NewUserMessage
+// or constructing with the given role.
+func makeTextMsg(role, text string) kit.LLMMessage {
+	return kit.LLMMessage{
+		Role:    kit.LLMMessageRole(role),
 		Content: []fantasy.MessagePart{fantasy.TextPart{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 {
+			return tp.Text
+		}
+	}
+	return ""
+}
+
 // --------------------------------------------------------------------------
 // NewMessageStore / NewMessageStoreWithMessages
 // --------------------------------------------------------------------------
@@ -29,7 +42,7 @@ func TestNewMessageStore_empty(t *testing.T) {
 }
 
 func TestNewMessageStoreWithMessages_preloaded(t *testing.T) {
-	msgs := []fantasy.Message{
+	msgs := []kit.LLMMessage{
 		makeTextMsg("user", "hello"),
 		makeTextMsg("assistant", "hi"),
 	}
@@ -42,7 +55,7 @@ func TestNewMessageStoreWithMessages_preloaded(t *testing.T) {
 // NewMessageStoreWithMessages must deep-copy the slice so that external
 // modifications don't affect the store.
 func TestNewMessageStoreWithMessages_isolatesInput(t *testing.T) {
-	msgs := []fantasy.Message{makeTextMsg("user", "hello")}
+	msgs := []kit.LLMMessage{makeTextMsg("user", "hello")}
 	s := NewMessageStoreWithMessages(msgs)
 
 	// Mutate the source slice.
@@ -52,9 +65,8 @@ func TestNewMessageStoreWithMessages_isolatesInput(t *testing.T) {
 	if len(got) != 1 {
 		t.Fatalf("expected 1 message, got %d", len(got))
 	}
-	tp, ok := got[0].Content[0].(fantasy.TextPart)
-	if !ok || tp.Text != "hello" {
-		t.Fatalf("store was mutated by external slice change; got %q", tp.Text)
+	if textOf(got[0]) != "hello" {
+		t.Fatalf("store was mutated by external slice change; got %q", textOf(got[0]))
 	}
 }
 
@@ -80,9 +92,8 @@ func TestAdd_preservesOrder(t *testing.T) {
 	}
 	got := s.GetAll()
 	for i, expected := range texts {
-		tp, ok := got[i].Content[0].(fantasy.TextPart)
-		if !ok || tp.Text != expected {
-			t.Fatalf("message[%d]: expected %q, got %q", i, expected, tp.Text)
+		if textOf(got[i]) != expected {
+			t.Fatalf("message[%d]: expected %q, got %q", i, expected, textOf(got[i]))
 		}
 	}
 }
@@ -95,7 +106,7 @@ func TestReplace_swapsHistory(t *testing.T) {
 	s := NewMessageStore()
 	s.Add(makeTextMsg("user", "old"))
 
-	replacement := []fantasy.Message{
+	replacement := []kit.LLMMessage{
 		makeTextMsg("user", "new1"),
 		makeTextMsg("assistant", "new2"),
 	}
@@ -105,25 +116,22 @@ func TestReplace_swapsHistory(t *testing.T) {
 		t.Fatalf("expected 2 messages after replace, got %d", s.Len())
 	}
 	got := s.GetAll()
-	tp0, _ := got[0].Content[0].(fantasy.TextPart)
-	tp1, _ := got[1].Content[0].(fantasy.TextPart)
-	if tp0.Text != "new1" || tp1.Text != "new2" {
-		t.Fatalf("unexpected messages after replace: %q %q", tp0.Text, tp1.Text)
+	if textOf(got[0]) != "new1" || textOf(got[1]) != "new2" {
+		t.Fatalf("unexpected messages after replace: %q %q", textOf(got[0]), textOf(got[1]))
 	}
 }
 
 // Replace must deep-copy the incoming slice.
 func TestReplace_isolatesInput(t *testing.T) {
 	s := NewMessageStore()
-	replacement := []fantasy.Message{makeTextMsg("user", "original")}
+	replacement := []kit.LLMMessage{makeTextMsg("user", "original")}
 	s.Replace(replacement)
 
 	replacement[0] = makeTextMsg("user", "mutated")
 
 	got := s.GetAll()
-	tp, _ := got[0].Content[0].(fantasy.TextPart)
-	if tp.Text != "original" {
-		t.Fatalf("store was mutated by external slice change after Replace; got %q", tp.Text)
+	if textOf(got[0]) != "original" {
+		t.Fatalf("store was mutated by external slice change after Replace; got %q", textOf(got[0]))
 	}
 }
 
@@ -140,9 +148,8 @@ func TestGetAll_returnsCopy(t *testing.T) {
 	got[0] = makeTextMsg("user", "mutated")
 
 	internal := s.GetAll()
-	tp, _ := internal[0].Content[0].(fantasy.TextPart)
-	if tp.Text != "hello" {
-		t.Fatalf("GetAll returned non-copy; store was mutated to %q", tp.Text)
+	if textOf(internal[0]) != "hello" {
+		t.Fatalf("GetAll returned non-copy; store was mutated to %q", textOf(internal[0]))
 	}
 }
 
@@ -179,9 +186,8 @@ func TestClear_allowsSubsequentAdds(t *testing.T) {
 		t.Fatalf("expected 1 message after Clear+Add, got %d", s.Len())
 	}
 	got := s.GetAll()
-	tp, _ := got[0].Content[0].(fantasy.TextPart)
-	if tp.Text != "after" {
-		t.Fatalf("expected %q, got %q", "after", tp.Text)
+	if textOf(got[0]) != "after" {
+		t.Fatalf("expected %q, got %q", "after", textOf(got[0]))
 	}
 }
 

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)
 }
 
@@ -67,10 +69,6 @@ type Options struct {
 	// Debug enables verbose debug logging.
 	Debug bool
 
-	// CompactMode selects the compact renderer instead of the block renderer for
-	// message formatting.
-	CompactMode bool
-
 	// UsageTracker is an optional callback for recording token usage after each
 	// agent step. When non-nil, the app layer calls UpdateUsage (or
 	// EstimateAndUpdateUsage as a fallback) using the usage data returned by the

internal/auth/credentials.go

@@ -10,9 +10,10 @@ import (
 )
 
 // CredentialStore holds all stored credentials for various providers.
-// Currently supports Anthropic credentials with both OAuth and API key authentication methods.
+// Currently supports Anthropic and OpenAI credentials with both OAuth and API key authentication methods.
 type CredentialStore struct {
 	Anthropic *AnthropicCredentials `json:"anthropic,omitempty"`
+	OpenAI    *OpenAICredentials    `json:"openai,omitempty"`
 }
 
 // AnthropicCredentials holds Anthropic API credentials supporting both OAuth
@@ -28,13 +29,44 @@ type AnthropicCredentials struct {
 	CreatedAt    time.Time `json:"created_at"`
 }
 
+// OpenAICredentials holds OpenAI API credentials supporting both OAuth
+// and API key authentication methods. The Type field indicates which authentication
+// method is being used. For OAuth, tokens are stored with expiration timestamps
+// for automatic refresh. For API keys, only the key itself is stored.
+type OpenAICredentials struct {
+	Type         string    `json:"type"`                    // "oauth" or "api_key"
+	APIKey       string    `json:"api_key,omitempty"`       // For API key auth
+	AccessToken  string    `json:"access_token,omitempty"`  // For OAuth
+	RefreshToken string    `json:"refresh_token,omitempty"` // For OAuth
+	ExpiresAt    int64     `json:"expires_at,omitempty"`    // For OAuth
+	AccountID    string    `json:"account_id,omitempty"`    // For OAuth (ChatGPT account ID)
+	CreatedAt    time.Time `json:"created_at"`
+}
+
+// oauthTokenExpired reports whether an OAuth token with the given type and
+// expiry unix timestamp is past its expiry. Returns false for API key
+// credentials or when no expiry is set.
+func oauthTokenExpired(credType string, expiresAt int64) bool {
+	if credType != "oauth" || expiresAt == 0 {
+		return false
+	}
+	return time.Now().Unix() >= expiresAt
+}
+
+// oauthTokenNeedsRefresh reports whether an OAuth token will expire within the
+// next 5 minutes, allowing proactive refresh before it becomes invalid.
+// Returns false for API key credentials or when no expiry is set.
+func oauthTokenNeedsRefresh(credType string, expiresAt int64) bool {
+	if credType != "oauth" || expiresAt == 0 {
+		return false
+	}
+	return time.Now().Unix() >= (expiresAt - 300) // 5 minutes buffer
+}
+
 // IsExpired checks if the OAuth token is expired based on the ExpiresAt timestamp.
 // Returns false for API key authentication or if no expiration is set.
 func (c *AnthropicCredentials) IsExpired() bool {
-	if c.Type != "oauth" || c.ExpiresAt == 0 {
-		return false
-	}
-	return time.Now().Unix() >= c.ExpiresAt
+	return oauthTokenExpired(c.Type, c.ExpiresAt)
 }
 
 // NeedsRefresh checks if the OAuth token needs refresh, returning true if the token
@@ -42,10 +74,21 @@ func (c *AnthropicCredentials) IsExpired() bool {
 // to avoid authentication failures during operations. Returns false for API key
 // authentication or if no expiration is set.
 func (c *AnthropicCredentials) NeedsRefresh() bool {
-	if c.Type != "oauth" || c.ExpiresAt == 0 {
-		return false
-	}
-	return time.Now().Unix() >= (c.ExpiresAt - 300) // 5 minutes buffer
+	return oauthTokenNeedsRefresh(c.Type, c.ExpiresAt)
+}
+
+// IsExpired checks if the OAuth token is expired based on the ExpiresAt timestamp.
+// Returns false for API key authentication or if no expiration is set.
+func (c *OpenAICredentials) IsExpired() bool {
+	return oauthTokenExpired(c.Type, c.ExpiresAt)
+}
+
+// NeedsRefresh checks if the OAuth token needs refresh, returning true if the token
+// will expire within the next 5 minutes. This allows for proactive token refresh
+// to avoid authentication failures during operations. Returns false for API key
+// authentication or if no expiration is set.
+func (c *OpenAICredentials) NeedsRefresh() bool {
+	return oauthTokenNeedsRefresh(c.Type, c.ExpiresAt)
 }
 
 // CredentialManager handles secure storage and retrieval of authentication credentials.
@@ -212,6 +255,142 @@ func (cm *CredentialManager) HasAnthropicCredentials() (bool, error) {
 	}
 }
 
+// SetOpenAICredentials stores OpenAI API key credentials. It validates the
+// API key format before storing. The API key must start with "sk-" and be
+// at least 20 characters long. Returns an error if the API key is invalid or
+// if storage fails.
+func (cm *CredentialManager) SetOpenAICredentials(apiKey string) error {
+	if err := validateOpenAIAPIKey(apiKey); err != nil {
+		return err
+	}
+
+	store, err := cm.LoadCredentials()
+	if err != nil {
+		return err
+	}
+
+	store.OpenAI = &OpenAICredentials{
+		Type:      "api_key",
+		APIKey:    apiKey,
+		CreatedAt: time.Now(),
+	}
+
+	return cm.SaveCredentials(store)
+}
+
+// GetOpenAICredentials retrieves stored OpenAI credentials. Returns nil if
+// no credentials are stored. The returned credentials may be either OAuth or API
+// key type, check the Type field to determine which.
+func (cm *CredentialManager) GetOpenAICredentials() (*OpenAICredentials, error) {
+	store, err := cm.LoadCredentials()
+	if err != nil {
+		return nil, err
+	}
+
+	return store.OpenAI, nil
+}
+
+// RemoveOpenAICredentials removes stored OpenAI credentials from storage.
+// If this was the only credential stored, the entire credentials file is removed.
+// Returns an error if the removal fails.
+func (cm *CredentialManager) RemoveOpenAICredentials() error {
+	store, err := cm.LoadCredentials()
+	if err != nil {
+		return err
+	}
+
+	store.OpenAI = nil
+
+	// If store is empty, remove the file entirely
+	if store.Anthropic == nil && store.OpenAI == nil {
+		if err := os.Remove(cm.credentialsPath); err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("failed to remove credentials file: %w", err)
+		}
+		return nil
+	}
+
+	return cm.SaveCredentials(store)
+}
+
+// HasOpenAICredentials checks if valid OpenAI credentials are stored.
+// Returns true if either a non-empty OAuth access token or API key is present,
+// false otherwise. Returns an error if credentials cannot be loaded.
+func (cm *CredentialManager) HasOpenAICredentials() (bool, error) {
+	creds, err := cm.GetOpenAICredentials()
+	if err != nil {
+		return false, err
+	}
+	if creds == nil {
+		return false, nil
+	}
+
+	// Check based on credential type
+	switch creds.Type {
+	case "oauth":
+		return creds.AccessToken != "", nil
+	case "api_key":
+		return creds.APIKey != "", nil
+	default:
+		return false, nil
+	}
+}
+
+// SetOpenAIOAuthCredentials stores OpenAI OAuth credentials in the credential manager's secure storage.
+// The credentials should include access token, refresh token, and expiration information.
+// Returns an error if the credentials cannot be saved.
+func (cm *CredentialManager) SetOpenAIOAuthCredentials(creds *OpenAICredentials) error {
+	store, err := cm.LoadCredentials()
+	if err != nil {
+		return err
+	}
+
+	store.OpenAI = creds
+	return cm.SaveCredentials(store)
+}
+
+// GetValidOpenAIAccessToken returns a valid access token for API requests. For OAuth credentials,
+// it automatically refreshes the token if it's expired or about to expire. For API key
+// credentials, it simply returns the API key. Returns an error if no credentials are found,
+// if token refresh fails, or if the credential type is unknown.
+func (cm *CredentialManager) GetValidOpenAIAccessToken() (string, error) {
+	creds, err := cm.GetOpenAICredentials()
+	if err != nil {
+		return "", err
+	}
+
+	if creds == nil {
+		return "", fmt.Errorf("no credentials found")
+	}
+
+	// For API key auth, return the API key
+	if creds.Type == "api_key" {
+		return creds.APIKey, nil
+	}
+
+	// For OAuth, check if token needs refresh
+	if creds.Type == "oauth" {
+		if creds.NeedsRefresh() {
+			// Refresh the token
+			client := NewOpenAIOAuthClient()
+			newCreds, err := client.RefreshToken(creds.RefreshToken)
+			if err != nil {
+				return "", fmt.Errorf("failed to refresh token: %w", err)
+			}
+
+			// Update stored credentials
+			if err := cm.SetOpenAIOAuthCredentials(newCreds); err != nil {
+				return "", fmt.Errorf("failed to save refreshed token: %w", err)
+			}
+
+			return newCreds.AccessToken, nil
+		}
+
+		return creds.AccessToken, nil
+	}
+
+	return "", fmt.Errorf("unknown credential type: %s", creds.Type)
+}
+
 // GetCredentialsPath returns the absolute path to the credentials JSON file.
 // This is useful for debugging or displaying the storage location to users.
 func (cm *CredentialManager) GetCredentialsPath() string {
@@ -238,6 +417,26 @@ func validateAnthropicAPIKey(apiKey string) error {
 	return nil
 }
 
+// validateOpenAIAPIKey validates the format of an OpenAI API key
+func validateOpenAIAPIKey(apiKey string) error {
+	apiKey = strings.TrimSpace(apiKey)
+
+	if apiKey == "" {
+		return fmt.Errorf("API key cannot be empty")
+	}
+
+	// OpenAI API keys typically start with "sk-" and are quite long
+	if !strings.HasPrefix(apiKey, "sk-") {
+		return fmt.Errorf("invalid OpenAI API key format (should start with 'sk-')")
+	}
+
+	if len(apiKey) < 20 {
+		return fmt.Errorf("API key appears to be too short")
+	}
+
+	return nil
+}
+
 // GetAnthropicAPIKey retrieves an Anthropic API key from multiple sources in priority order:
 // 1. Command-line flag value (highest priority)
 // 2. Stored credentials (OAuth or API key)

internal/auth/credentials_test.go

@@ -51,6 +51,7 @@ func TestCredentialManager(t *testing.T) {
 	}
 	if creds == nil {
 		t.Fatal("Expected credentials to be returned")
+		return
 	}
 	if creds.APIKey != testAPIKey {
 		t.Errorf("Expected API key %s, got %s", testAPIKey, creds.APIKey)
@@ -236,6 +237,7 @@ func TestCredentialStorePersistence(t *testing.T) {
 	}
 	if creds == nil {
 		t.Fatal("Expected credentials to persist")
+		return
 	}
 	if creds.APIKey != testAPIKey {
 		t.Errorf("Expected API key %s, got %s", testAPIKey, creds.APIKey)

internal/auth/oauth.go

@@ -7,6 +7,7 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net/http"
 	"net/url"
 	"strings"
@@ -30,6 +31,7 @@ type OAuthClient struct {
 type AuthData struct {
 	URL      string
 	Verifier string
+	State    string // Optional state parameter for CSRF protection
 }
 
 // NewOAuthClient creates a new OAuth client configured for Anthropic's OAuth service.
@@ -49,12 +51,12 @@ func NewOAuthClient() *OAuthClient {
 	}
 }
 
-// GeneratePKCE generates a cryptographically secure PKCE verifier and challenge pair
+// generatePKCE generates a cryptographically secure PKCE verifier and challenge pair
 // for the OAuth 2.0 PKCE flow. The verifier is a random 32-byte string encoded as
 // base64url, and the challenge is the SHA256 hash of the verifier, also base64url encoded.
 // Returns the verifier (to be stored securely), challenge (to be sent with auth request),
 // and any error encountered during generation.
-func GeneratePKCE() (verifier, challenge string, err error) {
+func generatePKCE() (verifier, challenge string, err error) {
 	// Generate 32 bytes of random data
 	verifierBytes := make([]byte, 32)
 	if _, err := rand.Read(verifierBytes); err != nil {
@@ -76,7 +78,7 @@ func GeneratePKCE() (verifier, challenge string, err error) {
 // and PKCE challenge. Returns an AuthData structure containing the URL for user
 // authentication and the PKCE verifier for the subsequent code exchange.
 func (c *OAuthClient) GetAuthorizationURL() (*AuthData, error) {
-	verifier, challenge, err := GeneratePKCE()
+	verifier, challenge, err := generatePKCE()
 	if err != nil {
 		return nil, fmt.Errorf("failed to generate PKCE: %w", err)
 	}
@@ -199,6 +201,270 @@ func (c *OAuthClient) parseCodeAndState(code string) (parsedCode, parsedState st
 	return
 }
 
+// OpenAIOAuthClient handles OAuth 2.0 authentication flow with OpenAI Codex (ChatGPT Plus/Pro).
+// This uses OpenAI's auth0-based OAuth service for ChatGPT account authentication.
+type OpenAIOAuthClient struct {
+	ClientID     string
+	AuthorizeURL string
+	TokenURL     string
+	RedirectURI  string
+	Scopes       string
+}
+
+// NewOpenAIOAuthClient creates a new OAuth client configured for OpenAI Codex OAuth.
+// This uses the public client ID for CLI applications with PKCE for security.
+func NewOpenAIOAuthClient() *OpenAIOAuthClient {
+	return &OpenAIOAuthClient{
+		// Public client ID for OpenAI Codex CLI OAuth
+		ClientID:     "app_EMoamEEZ73f0CkXaXp7hrann",
+		AuthorizeURL: "https://auth.openai.com/oauth/authorize",
+		TokenURL:     "https://auth.openai.com/oauth/token",
+		RedirectURI:  "http://localhost:1455/auth/callback",
+		Scopes:       "openid profile email offline_access",
+	}
+}
+
+// GetAuthorizationURL generates a complete authorization URL for the OAuth flow with
+// PKCE parameters. Returns an AuthData structure containing the URL for user
+// authentication and the PKCE verifier for the subsequent code exchange.
+func (c *OpenAIOAuthClient) GetAuthorizationURL() (*AuthData, error) {
+	verifier, challenge, err := generatePKCE()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate PKCE: %w", err)
+	}
+
+	// Generate random state
+	stateBytes := make([]byte, 16)
+	if _, err := rand.Read(stateBytes); err != nil {
+		return nil, fmt.Errorf("failed to generate state: %w", err)
+	}
+	state := fmt.Sprintf("%x", stateBytes)
+
+	params := url.Values{
+		"response_type":              {"code"},
+		"client_id":                  {c.ClientID},
+		"redirect_uri":               {c.RedirectURI},
+		"scope":                      {c.Scopes},
+		"code_challenge":             {challenge},
+		"code_challenge_method":      {"S256"},
+		"state":                      {state},
+		"id_token_add_organizations": {"true"},
+		"codex_cli_simplified_flow":  {"true"},
+		"originator":                 {"kit"},
+	}
+
+	authURL := fmt.Sprintf("%s?%s", c.AuthorizeURL, params.Encode())
+
+	return &AuthData{
+		URL:      authURL,
+		Verifier: verifier,
+		State:    state,
+	}, nil
+}
+
+// ExchangeCode exchanges an authorization code for access and refresh tokens.
+// The code parameter should be the authorization code received from the OAuth callback.
+// The verifier parameter must be the same PKCE verifier generated during GetAuthorizationURL.
+// Returns OpenAICredentials containing the tokens, expiration, and account ID.
+func (c *OpenAIOAuthClient) ExchangeCode(code, verifier string) (*OpenAICredentials, error) {
+	return c.exchangeAuthorizationCode(code, verifier, c.RedirectURI)
+}
+
+// exchangeAuthorizationCode performs the token exchange with the OAuth server
+func (c *OpenAIOAuthClient) exchangeAuthorizationCode(code, verifier, redirectUri string) (*OpenAICredentials, error) {
+	data := url.Values{
+		"grant_type":    {"authorization_code"},
+		"client_id":     {c.ClientID},
+		"code":          {code},
+		"code_verifier": {verifier},
+		"redirect_uri":  {redirectUri},
+	}
+
+	req, err := http.NewRequestWithContext(context.Background(), "POST", c.TokenURL, strings.NewReader(data.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	client := &http.Client{Timeout: 30 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to make token request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("token exchange failed: %s", string(body))
+	}
+
+	var tokenResp struct {
+		AccessToken  string `json:"access_token"`
+		RefreshToken string `json:"refresh_token"`
+		ExpiresIn    int    `json:"expires_in"`
+		IDToken      string `json:"id_token"`
+	}
+
+	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
+		return nil, fmt.Errorf("failed to decode token response: %w", err)
+	}
+
+	if tokenResp.AccessToken == "" || tokenResp.RefreshToken == "" {
+		return nil, fmt.Errorf("token response missing required fields")
+	}
+
+	// Extract account ID from JWT token
+	accountID := extractOpenAIAccountID(tokenResp.AccessToken)
+	if accountID == "" {
+		return nil, fmt.Errorf("failed to extract account ID from token")
+	}
+
+	return &OpenAICredentials{
+		Type:         "oauth",
+		AccessToken:  tokenResp.AccessToken,
+		RefreshToken: tokenResp.RefreshToken,
+		ExpiresAt:    time.Now().Unix() + int64(tokenResp.ExpiresIn),
+		CreatedAt:    time.Now(),
+		AccountID:    accountID,
+	}, nil
+}
+
+// RefreshToken refreshes an expired or expiring access token using a refresh token.
+// Returns new OpenAICredentials with updated access token, refresh token (may be
+// rotated), and new expiration timestamp. Returns an error if the refresh fails or
+// the refresh token is invalid.
+func (c *OpenAIOAuthClient) RefreshToken(refreshToken string) (*OpenAICredentials, error) {
+	data := url.Values{
+		"grant_type":    {"refresh_token"},
+		"refresh_token": {refreshToken},
+		"client_id":     {c.ClientID},
+	}
+
+	req, err := http.NewRequestWithContext(context.Background(), "POST", c.TokenURL, strings.NewReader(data.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	client := &http.Client{Timeout: 30 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to make refresh request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("token refresh failed: %s", string(body))
+	}
+
+	var tokenResp struct {
+		AccessToken  string `json:"access_token"`
+		RefreshToken string `json:"refresh_token"`
+		ExpiresIn    int    `json:"expires_in"`
+	}
+
+	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
+		return nil, fmt.Errorf("failed to decode refresh response: %w", err)
+	}
+
+	if tokenResp.AccessToken == "" || tokenResp.RefreshToken == "" {
+		return nil, fmt.Errorf("refresh response missing required fields")
+	}
+
+	// Extract account ID from JWT token
+	accountID := extractOpenAIAccountID(tokenResp.AccessToken)
+	if accountID == "" {
+		return nil, fmt.Errorf("failed to extract account ID from refreshed token")
+	}
+
+	return &OpenAICredentials{
+		Type:         "oauth",
+		AccessToken:  tokenResp.AccessToken,
+		RefreshToken: tokenResp.RefreshToken,
+		ExpiresAt:    time.Now().Unix() + int64(tokenResp.ExpiresIn),
+		CreatedAt:    time.Now(),
+		AccountID:    accountID,
+	}, nil
+}
+
+// extractOpenAIAccountID extracts the ChatGPT account ID from a JWT access token.
+// The account ID is stored in the claim path https://api.openai.com/auth.chatgpt_account_id
+func extractOpenAIAccountID(token string) string {
+	// JWT tokens are base64-encoded JSON payloads
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		return ""
+	}
+
+	// Decode payload (second part)
+	payload := parts[1]
+	// Add padding if needed
+	if len(payload)%4 != 0 {
+		payload += strings.Repeat("=", 4-len(payload)%4)
+	}
+
+	decoded, err := base64.URLEncoding.DecodeString(payload)
+	if err != nil {
+		return ""
+	}
+
+	var claims map[string]any
+	if err := json.Unmarshal(decoded, &claims); err != nil {
+		return ""
+	}
+
+	// Navigate to the claim path: https://api.openai.com/auth.chatgpt_account_id
+	authPath, ok := claims["https://api.openai.com/auth"].(map[string]any)
+	if !ok {
+		return ""
+	}
+
+	accountID, ok := authPath["chatgpt_account_id"].(string)
+	if !ok {
+		return ""
+	}
+
+	return accountID
+}
+
+// ParseOpenAIAuthorizationInput parses various forms of authorization input:
+// - Full callback URL: http://localhost:1455/auth/callback?code=xxx&state=yyy
+// - Code#State format: abc123#state456
+// - Query string: code=abc123&state=state456
+// - Just the code: abc123
+func ParseOpenAIAuthorizationInput(input string) (code, state string) {
+	input = strings.TrimSpace(input)
+	if input == "" {
+		return "", ""
+	}
+
+	// Try parsing as URL
+	if strings.HasPrefix(input, "http") {
+		if u, err := url.Parse(input); err == nil {
+			return u.Query().Get("code"), u.Query().Get("state")
+		}
+	}
+
+	// Try code#state format
+	if strings.Contains(input, "#") {
+		parts := strings.SplitN(input, "#", 2)
+		return parts[0], parts[1]
+	}
+
+	// Try query string format
+	if strings.Contains(input, "code=") {
+		if values, err := url.ParseQuery(input); err == nil {
+			return values.Get("code"), values.Get("state")
+		}
+	}
+
+	// Assume it's just the code
+	return input, ""
+}
+
 // SetOAuthCredentials stores OAuth credentials in the credential manager's secure storage.
 // The credentials should include access token, refresh token, and expiration information.
 // Returns an error if the credentials cannot be saved.

internal/clipboard/clipboard.go

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

internal/clipboard/clipboard_darwin.go

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

internal/clipboard/clipboard_integration_test.go

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

internal/clipboard/clipboard_linux.go

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