fix(mcp): surface MCP tool failures as soft errors, not critical aborts

The MCP adapter previously wrapped any error returned by MCPToolManager.ExecuteTool
into a Go error returned from the fantasy.AgentTool.Run interface. The fantasy
agent loop treats those as critical errors and aborts the entire turn —
discarding all prior reasoning, tool calls, and results.

In practice that meant a single misbehaved MCP server returning a JSON-RPC
"-32602 Invalid params" (e.g. a Zod schema mismatch on the server's input
validation) would kill an in-progress turn after the model had already done
dozens of seconds of useful work, with no way for the model to see the
validation message and self-correct.

This mismatched the contract that native Kit tools follow: native tools
return errors via kit.ErrorResult(...), which become soft tool-result errors
that the model reads and can act on (retry with corrected args, try a
different tool, give up gracefully).

Make the MCP path behave the same way:

  - JSON-RPC protocol errors, transport failures, and server-side schema
    rejections are now returned as fantasy.NewTextErrorResponse(...) with
    err == nil, so the agent loop continues and the model sees the failure
    in-band as a tool result it can reason about.
  - Context cancellation (ctx.Err() != nil) remains a critical error so
    callers can abort turns deterministically. This is the only case where
    bubbling up is correct — the caller intentionally tore the turn down
    and the agent must not keep spinning.
  - Server-side soft errors (CallToolResult{ isError: true }) and the
    happy path are unchanged.

The agent loop's MaxSteps cap already bounds the worst case for a
permanently broken MCP server, so there is no risk of unbounded retries.

Side effect: extracted a tiny mcpExecutor interface for the one method the
adapter uses (ExecuteTool), purely so the adapter is unit-testable in
isolation without standing up a full MCPToolManager + connection pool.

Behavior change note for downstream consumers: code that relied on
host.PromptResult / Stream returning a Go error containing
"mcp tool execution failed" will no longer see those errors — the
failure information is now in the assistant's final response (or in the
OnAfterToolResult / OnToolResult hooks, where IsError will be true).
Context cancellation continues to surface as an error from those calls
as before.

.kit/prompts/code-audit.md

@@ -0,0 +1,146 @@
+---
+description: Read-only audit for dead code, duplication, boundary violations, and refactor opportunities
+---
+
+Perform a comprehensive **read-only** audit of this repository and report
+findings. **Do not edit, rename, or delete any files.** Optional focus / scope
+hints from the user: $@
+
+## Scope
+
+If the user supplied focus hints above (a package path, a subsystem name, a
+concern like "TUI" or "extensions"), scope the audit accordingly. Otherwise
+audit the whole repo, prioritising the highest-traffic packages first
+(`cmd/`, `internal/`, `pkg/kit/` for this repo).
+
+## Steps
+
+1. **Map the repo first**:
+   - `ls` / `find` the top-level layout and list every Go package
+   - Read `AGENTS.md`, `README.md`, and any `pkg/*/doc.go` to understand the
+     intended architectural boundaries (SDK vs internal vs TUI vs cmd vs
+     extension surface)
+   - Note the public SDK surface (`pkg/kit/`) and any documented invariants
+     (e.g. "no dependency name leakage", "UI never imports extensions
+     directly") — these define what counts as a violation
+
+2. **Hunt for dead code**:
+   - Run `go vet ./...` and capture warnings
+   - Use `grep` to find exported symbols (`^func [A-Z]`, `^type [A-Z]`,
+     `^var [A-Z]`, `^const [A-Z]`) and cross-reference call sites. Symbols
+     with zero non-test references inside the module are suspects
+   - Check for unreferenced files, `// TODO: remove` markers, commented-out
+     blocks, and `_ = x` discard patterns
+   - If `staticcheck`, `deadcode`, or `unused` are available on PATH, run
+     them and include their output verbatim
+   - **Do not delete anything** — list candidates with file:line and a
+     confidence level (high / medium / low)
+
+3. **Find unnecessary duplication**:
+   - Look for near-identical function bodies, struct shapes, or switch
+     statements across packages — `grep` for repeated function signatures
+     and copy-pasted string literals / error messages is a fast first pass
+   - Distinguish *coincidental* duplication (two things that happen to look
+     alike but evolve independently) from *unnecessary* duplication (same
+     intent, drifting in lockstep) — only flag the latter
+   - For each cluster, propose where the extracted helper should live
+     (which package, which file) and whether it crosses a boundary
+
+4. **Check concerns / boundary violations**:
+   - **SDK leakage**: grep `pkg/kit/` for imports of `internal/...` types
+     in exported signatures, and for dependency-name leakage in exported
+     names / godoc (e.g. library jargon appearing in `LLM*` types)
+   - **UI ↔ extensions**: grep `internal/ui/` for any import of
+     `internal/extensions/` — per AGENTS.md the UI must not import
+     extensions directly; converters in `cmd/root.go` should bridge them
+   - **cmd vs internal**: business logic living in `cmd/` that should be
+     in `internal/` (and vice versa)
+   - **Cyclic risk**: packages that import each other transitively or that
+     reach across sibling boundaries unexpectedly
+   - For each violation, cite the offending import / signature with
+     file:line
+
+5. **Spot refactor opportunities**:
+   - Long functions (>80 lines) doing multiple unrelated things
+   - Deeply nested conditionals that flatten well with early returns
+   - Repeated `if err != nil { return fmt.Errorf("...: %w", err) }` chains
+     that could become helpers — but only where the wrapping context is
+     genuinely uniform
+   - Structs with too many fields that hint at split responsibilities
+   - Exported APIs that would be cleaner with options structs / functional
+     options
+   - Tests that share setup boilerplate ripe for a helper
+   - Flag each with: location, current shape (1-2 lines), proposed shape
+     (1-2 lines), and estimated risk (low / medium / high)
+
+6. **Cross-check against project rules**:
+   - Re-read `AGENTS.md` "Key Patterns" section and verify nothing in your
+     findings contradicts the documented gotchas (Yaegi interface ban,
+     `prog.Send()` from `Update()`, function-field bug, etc.) — if a
+     "refactor" would reintroduce a known pitfall, drop it from the report
+     and note why
+
+7. **Write the report** as your final message (do not write it to disk)
+   structured as:
+
+   ```
+   # Code Audit Report
+
+   ## Summary
+   - N dead-code candidates
+   - N duplication clusters
+   - N boundary violations
+   - N refactor opportunities
+
+   ## Dead Code
+   ### High confidence
+   - path/to/file.go:LINE — symbol — reason
+
+   ### Medium confidence
+   ...
+
+   ## Duplication
+   ### Cluster: <short name>
+   - Sites: file:line, file:line, …
+   - Suggested home: package/path
+   - Notes: …
+
+   ## Boundary Violations
+   - Rule: <which rule from AGENTS.md / project convention>
+   - Offender: file:line
+   - Fix sketch: …
+
+   ## Refactor Opportunities
+   - Location: file:line
+   - Current: …
+   - Proposed: …
+   - Risk: low/medium/high
+   - Why it's worth it: …
+
+   ## Suggested Next Steps
+   1. …
+   2. …
+   ```
+
+8. **End the report with an explicit reminder** that no files were modified,
+   and recommend the user pick the highest-leverage items to act on
+   manually (or via a follow-up `/fix-issue` style prompt) rather than
+   running a sweeping refactor.
+
+## Guidelines
+
+- **Read-only, always**: no `edit`, no `write`, no `git commit`, no `go mod
+  tidy`. Use only `read`, `grep`, `find`, `ls`, and read-only `bash`
+  commands (`go vet`, `go build -o /tmp/...`, `staticcheck`, etc.)
+- **Cite every finding** with `path/to/file.go:LINE` so the user can jump
+  straight to it
+- **Be honest about confidence**: false positives in a code audit are
+  expensive — prefer "medium confidence, worth a look" over confidently
+  wrong claims
+- **Quantity isn't quality**: 10 sharp findings beat 100 nitpicks. Cut
+  anything that's purely stylistic unless it directly causes one of the
+  four issue categories above
+- **Skip generated code** (`*.pb.go`, `*_gen.go`, anything under
+  `vendor/`) and obvious third-party copies
+- **Don't propose architectural rewrites** — stay within the existing
+  shape of the repo and recommend incremental, reviewable changes

cmd/extension_context.go

@@ -0,0 +1,473 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/viper"
+	"golang.org/x/term"
+
+	"github.com/mark3labs/kit/internal/app"
+	"github.com/mark3labs/kit/internal/auth"
+	"github.com/mark3labs/kit/internal/extbridge"
+	"github.com/mark3labs/kit/internal/extensions"
+	"github.com/mark3labs/kit/internal/models"
+	"github.com/mark3labs/kit/internal/ui"
+	kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+// extensionContextDeps groups the runtime dependencies needed to wire up
+// an extensions.Context for the interactive TUI mode.
+type extensionContextDeps struct {
+	ctx          context.Context
+	cwd          string
+	modelName    string
+	interactive  bool
+	kitInstance  *kit.Kit
+	appInstance  *app.App
+	usageTracker *ui.UsageTracker
+}
+
+// buildInteractiveExtensionContext returns an extensions.Context with every
+// field except Print / PrintInfo / PrintError populated. Callers must set
+// the three print routes appropriately for their phase (startup buffering
+// vs. live runtime routing).
+//
+// This consolidates two near-identical 400-line literal expressions that
+// previously appeared inline in runNormalMode.
+func buildInteractiveExtensionContext(deps extensionContextDeps) extensions.Context {
+	kitInstance := deps.kitInstance
+	appInstance := deps.appInstance
+	usageTracker := deps.usageTracker
+	ctx := deps.ctx
+
+	return extensions.Context{
+		CWD:         deps.cwd,
+		Model:       deps.modelName,
+		Interactive: deps.interactive,
+		PrintBlock: func(opts extensions.PrintBlockOpts) {
+			appInstance.PrintBlockFromExtension(opts)
+		},
+		SendMessage:   func(text string) { appInstance.Run(text) },
+		CancelAndSend: func(text string) { appInstance.InterruptAndSend(text) },
+		Abort:         func() { appInstance.Abort() },
+		IsIdle:        func() bool { return !appInstance.IsBusy() },
+		Compact: func(cfg extensions.CompactConfig) error {
+			return appInstance.CompactAsync(cfg.CustomInstructions, cfg.OnComplete, cfg.OnError)
+		},
+		SendMultimodalMessage: func(text string, files []extensions.FilePart) {
+			parts := make([]kit.LLMFilePart, len(files))
+			for i, f := range files {
+				parts[i] = kit.LLMFilePart{
+					Filename:  f.Filename,
+					Data:      f.Data,
+					MediaType: f.MediaType,
+				}
+			}
+			appInstance.RunWithFiles(text, parts)
+		},
+		GetSessionUsage: func() extensions.SessionUsage {
+			if usageTracker == nil {
+				return extensions.SessionUsage{}
+			}
+			stats := usageTracker.GetSessionStats()
+			return extensions.SessionUsage{
+				TotalInputTokens:      stats.TotalInputTokens,
+				TotalOutputTokens:     stats.TotalOutputTokens,
+				TotalCacheReadTokens:  stats.TotalCacheReadTokens,
+				TotalCacheWriteTokens: stats.TotalCacheWriteTokens,
+				TotalCost:             stats.TotalCost,
+				RequestCount:          stats.RequestCount,
+			}
+		},
+		Exit: func() { appInstance.QuitFromExtension() },
+		SetWidget: func(config extensions.WidgetConfig) {
+			kitInstance.Extensions().SetWidget(config)
+			go appInstance.NotifyWidgetUpdate()
+		},
+		RemoveWidget: func(id string) {
+			kitInstance.Extensions().RemoveWidget(id)
+			go appInstance.NotifyWidgetUpdate()
+		},
+		SetHeader: func(config extensions.HeaderFooterConfig) {
+			kitInstance.Extensions().SetHeader(config)
+			go appInstance.NotifyWidgetUpdate()
+		},
+		RemoveHeader: func() {
+			kitInstance.Extensions().RemoveHeader()
+			go appInstance.NotifyWidgetUpdate()
+		},
+		SetFooter: func(config extensions.HeaderFooterConfig) {
+			kitInstance.Extensions().SetFooter(config)
+			go appInstance.NotifyWidgetUpdate()
+		},
+		RemoveFooter: func() {
+			kitInstance.Extensions().RemoveFooter()
+			go appInstance.NotifyWidgetUpdate()
+		},
+		PromptSelect: func(config extensions.PromptSelectConfig) extensions.PromptSelectResult {
+			ch := make(chan app.PromptResponse, 1)
+			appInstance.SendPromptRequest(app.PromptRequestEvent{
+				PromptType: "select",
+				Message:    config.Message,
+				Options:    config.Options,
+				ResponseCh: ch,
+			})
+			resp := <-ch
+			if resp.Cancelled {
+				return extensions.PromptSelectResult{Cancelled: true}
+			}
+			return extensions.PromptSelectResult{Value: resp.Value, Index: resp.Index}
+		},
+		PromptConfirm: func(config extensions.PromptConfirmConfig) extensions.PromptConfirmResult {
+			ch := make(chan app.PromptResponse, 1)
+			def := "false"
+			if config.DefaultValue {
+				def = "true"
+			}
+			appInstance.SendPromptRequest(app.PromptRequestEvent{
+				PromptType: "confirm",
+				Message:    config.Message,
+				Default:    def,
+				ResponseCh: ch,
+			})
+			resp := <-ch
+			if resp.Cancelled {
+				return extensions.PromptConfirmResult{Cancelled: true}
+			}
+			return extensions.PromptConfirmResult{Value: resp.Confirmed}
+		},
+		PromptInput: func(config extensions.PromptInputConfig) extensions.PromptInputResult {
+			ch := make(chan app.PromptResponse, 1)
+			appInstance.SendPromptRequest(app.PromptRequestEvent{
+				PromptType:  "input",
+				Message:     config.Message,
+				Placeholder: config.Placeholder,
+				Default:     config.Default,
+				ResponseCh:  ch,
+			})
+			resp := <-ch
+			if resp.Cancelled {
+				return extensions.PromptInputResult{Cancelled: true}
+			}
+			return extensions.PromptInputResult{Value: resp.Value}
+		},
+		SetUIVisibility: func(v extensions.UIVisibility) {
+			kitInstance.Extensions().SetUIVisibility(v)
+			go appInstance.NotifyWidgetUpdate()
+		},
+		GetContextStats: func() extensions.ContextStats {
+			s := kitInstance.GetContextStats()
+			return extensions.ContextStats{
+				EstimatedTokens: s.EstimatedTokens,
+				ContextLimit:    s.ContextLimit,
+				UsagePercent:    s.UsagePercent,
+				MessageCount:    s.MessageCount,
+			}
+		},
+		SetEditor: func(config extensions.EditorConfig) {
+			kitInstance.Extensions().SetEditor(config)
+			// Always use a goroutine for NotifyWidgetUpdate: prog.Send()
+			// deadlocks if called synchronously from inside BubbleTea's
+			// Update() handler. All call sites use go-routines uniformly.
+			go appInstance.NotifyWidgetUpdate()
+		},
+		ResetEditor: func() {
+			kitInstance.Extensions().ResetEditor()
+			go appInstance.NotifyWidgetUpdate()
+		},
+		GetMessages: func() []extensions.SessionMessage {
+			return kitInstance.Extensions().GetSessionMessages()
+		},
+		GetSessionPath: func() string {
+			return kitInstance.GetSessionPath()
+		},
+		AppendEntry: func(entryType string, data string) (string, error) {
+			return kitInstance.Extensions().AppendEntry(entryType, data)
+		},
+		GetEntries: func(entryType string) []extensions.ExtensionEntry {
+			return kitInstance.Extensions().GetEntries(entryType)
+		},
+		SetEditorText: func(text string) {
+			appInstance.SetEditorTextFromExtension(text)
+		},
+		SetStatus: func(key string, text string, priority int) {
+			kitInstance.Extensions().SetStatus(extensions.StatusBarEntry{
+				Key:      key,
+				Text:     text,
+				Priority: priority,
+			})
+			go appInstance.NotifyWidgetUpdate()
+		},
+		RemoveStatus: func(key string) {
+			kitInstance.Extensions().RemoveStatus(key)
+			go appInstance.NotifyWidgetUpdate()
+		},
+		GetOption: func(name string) string {
+			return kitInstance.Extensions().GetOption(name)
+		},
+		SetOption: func(name string, value string) {
+			kitInstance.Extensions().SetOption(name, value)
+		},
+		SetModel: func(modelString string) error {
+			// Capture previous model for the ModelChange event.
+			previousModel := kitInstance.Extensions().GetContext().Model
+			err := kitInstance.SetModel(context.Background(), modelString)
+			if err != nil {
+				return err
+			}
+			// Notify TUI so it updates model in status bar.
+			p, m, _ := models.ParseModelString(modelString)
+			appInstance.NotifyModelChanged(p, m)
+			// Update the context's Model field so handlers see it.
+			kitInstance.Extensions().UpdateContextModel(modelString)
+			// Fire OnModelChange event to extensions.
+			kitInstance.Extensions().EmitModelChange(modelString, previousModel, "extension")
+			// Update usage tracker with new model info for correct token counting.
+			if usageTracker != nil {
+				newProvider, newModel, _ := models.ParseModelString(modelString)
+				if newProvider != "unknown" && newModel != "unknown" && newProvider != "ollama" {
+					registry := models.GetGlobalRegistry()
+					if modelInfo := registry.LookupModel(newProvider, newModel); modelInfo != nil {
+						// Check OAuth status for Anthropic models
+						isOAuth := false
+						if newProvider == "anthropic" {
+							_, source, err := auth.GetAnthropicAPIKey(viper.GetString("provider-api-key"))
+							if err == nil && strings.HasPrefix(source, "stored OAuth") {
+								isOAuth = true
+							}
+						}
+						usageTracker.UpdateModelInfo(modelInfo, newProvider, isOAuth)
+					}
+				}
+			}
+			return nil
+		},
+		GetAvailableModels: func() []extensions.ModelInfoEntry {
+			return kitInstance.GetAvailableModels()
+		},
+		EmitCustomEvent: func(name string, data string) {
+			kitInstance.Extensions().EmitCustomEvent(name, data)
+		},
+		Complete: func(req extensions.CompleteRequest) (extensions.CompleteResponse, error) {
+			return kitInstance.ExecuteCompletion(context.Background(), req)
+		},
+		SuspendTUI: func(callback func()) error {
+			return appInstance.SuspendTUI(callback)
+		},
+		RenderMessage: func(rendererName, content string) {
+			renderer := kitInstance.Extensions().GetMessageRenderer(rendererName)
+			if renderer == nil || renderer.Render == nil {
+				appInstance.PrintFromExtension("", content)
+				return
+			}
+			w, _, _ := term.GetSize(int(os.Stdout.Fd()))
+			if w == 0 {
+				w = 80
+			}
+			rendered := renderer.Render(content, w)
+			appInstance.PrintFromExtension("", rendered)
+		},
+		ReloadExtensions: func() error {
+			err := kitInstance.Extensions().Reload()
+			if err != nil {
+				return err
+			}
+			// Notify TUI that widgets/status/commands may have changed.
+			go appInstance.NotifyWidgetUpdate()
+			return nil
+		},
+		GetAllTools: func() []extensions.ToolInfo {
+			return kitInstance.Extensions().GetToolInfos()
+		},
+		SetActiveTools: func(names []string) {
+			kitInstance.Extensions().SetActiveTools(names)
+		},
+		RegisterTheme: func(name string, config extensions.ThemeColorConfig) {
+			tc := func(c extensions.ThemeColor) [2]string { return [2]string{c.Light, c.Dark} }
+			ui.RegisterThemeFromConfig(name,
+				tc(config.Primary), tc(config.Secondary),
+				tc(config.Success), tc(config.Warning),
+				tc(config.Error), tc(config.Info),
+				tc(config.Text), tc(config.Muted),
+				tc(config.VeryMuted), tc(config.Background),
+				tc(config.Border), tc(config.MutedBorder),
+				tc(config.System), tc(config.Tool),
+				tc(config.Accent), tc(config.Highlight),
+				tc(config.MdHeading), tc(config.MdLink),
+				tc(config.MdKeyword), tc(config.MdString),
+				tc(config.MdNumber), tc(config.MdComment),
+			)
+		},
+		SetTheme: func(name string) error {
+			return ui.ApplyTheme(name)
+		},
+		ListThemes: func() []string {
+			return ui.ListThemes()
+		},
+		ShowOverlay: func(config extensions.OverlayConfig) extensions.OverlayResult {
+			ch := make(chan app.OverlayResponse, 1)
+			appInstance.SendOverlayRequest(app.OverlayRequestEvent{
+				Title:       config.Title,
+				Content:     config.Content.Text,
+				Markdown:    config.Content.Markdown,
+				BorderColor: config.Style.BorderColor,
+				Background:  config.Style.Background,
+				Width:       config.Width,
+				MaxHeight:   config.MaxHeight,
+				Anchor:      string(config.Anchor),
+				Actions:     config.Actions,
+				ResponseCh:  ch,
+			})
+			resp := <-ch
+			if resp.Cancelled {
+				return extensions.OverlayResult{Cancelled: true, Index: -1}
+			}
+			return extensions.OverlayResult{
+				Action: resp.Action,
+				Index:  resp.Index,
+			}
+		},
+		SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
+			return extbridge.SpawnSubagent(ctx, kitInstance, config)
+		},
+		// -------------------------------------------------------------------
+		// Tree Navigation API
+		// -------------------------------------------------------------------
+		GetTreeNode: func(entryID string) *extensions.TreeNode {
+			node := kitInstance.GetTreeNode(entryID)
+			if node == nil {
+				return nil
+			}
+			return &extensions.TreeNode{
+				ID:        node.ID,
+				ParentID:  node.ParentID,
+				Type:      node.Type,
+				Role:      node.Role,
+				Content:   node.Content,
+				Model:     node.Model,
+				Provider:  node.Provider,
+				Timestamp: node.Timestamp,
+				Children:  node.Children,
+			}
+		},
+		GetCurrentBranch: func() []extensions.TreeNode {
+			nodes := kitInstance.GetCurrentBranch()
+			result := make([]extensions.TreeNode, len(nodes))
+			for i, n := range nodes {
+				result[i] = extensions.TreeNode{
+					ID:        n.ID,
+					ParentID:  n.ParentID,
+					Type:      n.Type,
+					Role:      n.Role,
+					Content:   n.Content,
+					Model:     n.Model,
+					Provider:  n.Provider,
+					Timestamp: n.Timestamp,
+					Children:  n.Children,
+				}
+			}
+			return result
+		},
+		GetChildren: func(parentID string) []string {
+			return kitInstance.GetChildren(parentID)
+		},
+		NavigateTo: func(entryID string) extensions.TreeNavigationResult {
+			err := kitInstance.NavigateTo(entryID)
+			if err != nil {
+				return extensions.TreeNavigationResult{Success: false, Error: err.Error()}
+			}
+			return extensions.TreeNavigationResult{Success: true}
+		},
+		SummarizeBranch: func(fromID, toID string) string {
+			summary, _ := kitInstance.SummarizeBranch(fromID, toID)
+			return summary
+		},
+		CollapseBranch: func(fromID, toID, summary string) extensions.TreeNavigationResult {
+			err := kitInstance.CollapseBranch(fromID, toID, summary)
+			if err != nil {
+				return extensions.TreeNavigationResult{Success: false, Error: err.Error()}
+			}
+			return extensions.TreeNavigationResult{Success: true}
+		},
+
+		// -------------------------------------------------------------------
+		// Skill Loading API
+		// -------------------------------------------------------------------
+		LoadSkill: func(path string) (*extensions.Skill, string) {
+			s, err := kitInstance.LoadSkillForExtension(path)
+			return s, err
+		},
+		LoadSkillsFromDir: func(dir string) extensions.SkillLoadResult {
+			return kitInstance.LoadSkillsFromDirForExtension(dir)
+		},
+		DiscoverSkills: func() extensions.SkillLoadResult {
+			skills := kitInstance.DiscoverSkillsForExtension()
+			return extensions.SkillLoadResult{Skills: skills}
+		},
+		InjectSkillAsContext: func(skillName string) string {
+			skills := kitInstance.DiscoverSkillsForExtension()
+			for _, s := range skills {
+				if s.Name == skillName {
+					appInstance.Run(fmt.Sprintf("<skill name=%q>\n%s\n</skill>", s.Name, s.Content))
+					return ""
+				}
+			}
+			return fmt.Sprintf("skill not found: %s", skillName)
+		},
+		InjectRawSkillAsContext: func(path string) string {
+			s, err := kitInstance.LoadSkillForExtension(path)
+			if err != "" {
+				return err
+			}
+			appInstance.Run(fmt.Sprintf("<skill name=%q>\n%s\n</skill>", s.Name, s.Content))
+			return ""
+		},
+		GetAvailableSkills: func() []extensions.Skill {
+			return kitInstance.DiscoverSkillsForExtension()
+		},
+
+		// -------------------------------------------------------------------
+		// Template Parsing API
+		// -------------------------------------------------------------------
+		ParseTemplate: func(name, content string) extensions.PromptTemplate {
+			return kit.ParseTemplate(name, content)
+		},
+		RenderTemplate: func(tpl extensions.PromptTemplate, vars map[string]string) string {
+			return kit.RenderTemplate(tpl, vars)
+		},
+		ParseArguments: func(input string, pattern extensions.ArgumentPattern) extensions.ParseResult {
+			return kit.ParseArguments(input, pattern)
+		},
+		SimpleParseArguments: func(input string, count int) []string {
+			return kit.SimpleParseArguments(input, count)
+		},
+		EvaluateModelConditional: func(condition string) bool {
+			return kit.EvaluateModelConditional(kitInstance.Extensions().GetContext().Model, condition)
+		},
+		RenderWithModelConditionals: func(content string) string {
+			return kit.RenderWithModelConditionals(content, kitInstance.Extensions().GetContext().Model)
+		},
+
+		// -------------------------------------------------------------------
+		// Model Resolution API
+		// -------------------------------------------------------------------
+		ResolveModelChain: func(preferences []string) extensions.ModelResolutionResult {
+			return kit.ResolveModelChain(preferences)
+		},
+		GetModelCapabilities: func(model string) (extensions.ModelCapabilities, string) {
+			return kit.GetModelCapabilities(model)
+		},
+		CheckModelAvailable: func(model string) bool {
+			return kit.CheckModelAvailable(model)
+		},
+		GetCurrentProvider: func() string {
+			return kit.GetCurrentProvider(kitInstance.Extensions().GetContext().Model)
+		},
+		GetCurrentModelID: func() string {
+			return kit.GetCurrentModelID(kitInstance.Extensions().GetContext().Model)
+		},
+	}
+}

cmd/root.go

@@ -169,12 +169,6 @@ func InitConfig() {
 	models.ReloadGlobalRegistry()
 }
 
-// LoadConfigWithEnvSubstitution loads a config file with environment variable
-// substitution. Delegates to the SDK implementation.
-func LoadConfigWithEnvSubstitution(configPath string) error {
-	return kit.LoadConfigWithEnvSubstitution(configPath)
-}
-
 // adaptiveOrDefault converts a config.AdaptiveColor to a resolved color.Color,
 // falling back to fallback when both Light and Dark are empty.
 func adaptiveOrDefault(ac config.AdaptiveColor, fallback color.Color) color.Color {
@@ -790,6 +784,16 @@ func runNormalMode(ctx context.Context) error {
 	}
 	defer func() { _ = kitInstance.Close() }()
 
+	// Build the "System Prompt loaded" notice shown at startup, paralleling the
+	// per-server "MCP server loaded" notifications so users can confirm that a
+	// configured prompt file was found and applied.
+	var systemPromptLoadedMsg string
+	if kitInstance.HasCustomSystemPrompt() {
+		if src := kitInstance.GetSystemPromptSource(); src != "" {
+			systemPromptLoadedMsg = "System Prompt loaded: " + src
+		}
+	}
+
 	// Extract metadata for display and app options.
 	parsedProvider, modelName, serverNames, toolNames, mcpToolCount, extensionToolCount := CollectAgentMetadata(kitInstance, mcpConfig)
 
@@ -807,6 +811,9 @@ func runNormalMode(ctx context.Context) error {
 		}
 
 		DisplayDebugConfig(cli, kitInstance, mcpConfig, parsedProvider)
+		if systemPromptLoadedMsg != "" && cli != nil {
+			cli.DisplayInfo(systemPromptLoadedMsg)
+		}
 	}
 
 	// Load existing messages from resumed/continued sessions.
@@ -846,763 +853,49 @@ func runNormalMode(ctx context.Context) error {
 
 	// Buffer for extension messages during startup (printed after startup banner).
 	var startupExtensionMessages []string
+	if systemPromptLoadedMsg != "" {
+		startupExtensionMessages = append(startupExtensionMessages, systemPromptLoadedMsg)
+	}
 
 	// Set up extension context and emit SessionStart.
 	if kitInstance.Extensions().HasExtensions() {
 		cwd, _ := os.Getwd()
-		kitInstance.Extensions().SetContext(extensions.Context{
-			CWD:         cwd,
-			Model:       modelName,
-			Interactive: positionalPrompt == "",
-			Print: func(text string) {
-				// Capture messages during startup, print after startup banner.
-				startupExtensionMessages = append(startupExtensionMessages, text)
-			},
-			PrintInfo: func(text string) {
-				startupExtensionMessages = append(startupExtensionMessages, text)
-			},
-			PrintError: func(text string) {
-				startupExtensionMessages = append(startupExtensionMessages, text)
-			},
-			PrintBlock:    appInstance.PrintBlockFromExtension,
-			SendMessage:   func(text string) { appInstance.Run(text) },
-			CancelAndSend: func(text string) { appInstance.InterruptAndSend(text) },
-			Abort:         func() { appInstance.Abort() },
-			IsIdle:        func() bool { return !appInstance.IsBusy() },
-			Compact: func(cfg extensions.CompactConfig) error {
-				return appInstance.CompactAsync(cfg.CustomInstructions, cfg.OnComplete, cfg.OnError)
-			},
-			SendMultimodalMessage: func(text string, files []extensions.FilePart) {
-				parts := make([]kit.LLMFilePart, len(files))
-				for i, f := range files {
-					parts[i] = kit.LLMFilePart{
-						Filename:  f.Filename,
-						Data:      f.Data,
-						MediaType: f.MediaType,
-					}
-				}
-				appInstance.RunWithFiles(text, parts)
-			},
-			GetSessionUsage: func() extensions.SessionUsage {
-				if usageTracker == nil {
-					return extensions.SessionUsage{}
-				}
-				stats := usageTracker.GetSessionStats()
-				return extensions.SessionUsage{
-					TotalInputTokens:      stats.TotalInputTokens,
-					TotalOutputTokens:     stats.TotalOutputTokens,
-					TotalCacheReadTokens:  stats.TotalCacheReadTokens,
-					TotalCacheWriteTokens: stats.TotalCacheWriteTokens,
-					TotalCost:             stats.TotalCost,
-					RequestCount:          stats.RequestCount,
-				}
-			},
-			Exit: func() { appInstance.QuitFromExtension() },
-			SetWidget: func(config extensions.WidgetConfig) {
-				kitInstance.Extensions().SetWidget(config)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			RemoveWidget: func(id string) {
-				kitInstance.Extensions().RemoveWidget(id)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			SetHeader: func(config extensions.HeaderFooterConfig) {
-				kitInstance.Extensions().SetHeader(config)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			RemoveHeader: func() {
-				kitInstance.Extensions().RemoveHeader()
-				go appInstance.NotifyWidgetUpdate()
-			},
-			SetFooter: func(config extensions.HeaderFooterConfig) {
-				kitInstance.Extensions().SetFooter(config)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			RemoveFooter: func() {
-				kitInstance.Extensions().RemoveFooter()
-				go appInstance.NotifyWidgetUpdate()
-			},
-			PromptSelect: func(config extensions.PromptSelectConfig) extensions.PromptSelectResult {
-				ch := make(chan app.PromptResponse, 1)
-				appInstance.SendPromptRequest(app.PromptRequestEvent{
-					PromptType: "select",
-					Message:    config.Message,
-					Options:    config.Options,
-					ResponseCh: ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.PromptSelectResult{Cancelled: true}
-				}
-				return extensions.PromptSelectResult{Value: resp.Value, Index: resp.Index}
-			},
-			PromptConfirm: func(config extensions.PromptConfirmConfig) extensions.PromptConfirmResult {
-				ch := make(chan app.PromptResponse, 1)
-				def := "false"
-				if config.DefaultValue {
-					def = "true"
-				}
-				appInstance.SendPromptRequest(app.PromptRequestEvent{
-					PromptType: "confirm",
-					Message:    config.Message,
-					Default:    def,
-					ResponseCh: ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.PromptConfirmResult{Cancelled: true}
-				}
-				return extensions.PromptConfirmResult{Value: resp.Confirmed}
-			},
-			PromptInput: func(config extensions.PromptInputConfig) extensions.PromptInputResult {
-				ch := make(chan app.PromptResponse, 1)
-				appInstance.SendPromptRequest(app.PromptRequestEvent{
-					PromptType:  "input",
-					Message:     config.Message,
-					Placeholder: config.Placeholder,
-					Default:     config.Default,
-					ResponseCh:  ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.PromptInputResult{Cancelled: true}
-				}
-				return extensions.PromptInputResult{Value: resp.Value}
-			},
-			SetUIVisibility: func(v extensions.UIVisibility) {
-				kitInstance.Extensions().SetUIVisibility(v)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			GetContextStats: func() extensions.ContextStats {
-				s := kitInstance.GetContextStats()
-				return extensions.ContextStats{
-					EstimatedTokens: s.EstimatedTokens,
-					ContextLimit:    s.ContextLimit,
-					UsagePercent:    s.UsagePercent,
-					MessageCount:    s.MessageCount,
-				}
-			},
-			SetEditor: func(config extensions.EditorConfig) {
-				kitInstance.Extensions().SetEditor(config)
-				// Always use a goroutine for NotifyWidgetUpdate: prog.Send()
-				// deadlocks if called synchronously from inside BubbleTea's
-				// Update() handler. All call sites use go-routines uniformly.
-				go appInstance.NotifyWidgetUpdate()
-			},
-			ResetEditor: func() {
-				kitInstance.Extensions().ResetEditor()
-				go appInstance.NotifyWidgetUpdate()
-			},
-			GetMessages: func() []extensions.SessionMessage {
-				return kitInstance.Extensions().GetSessionMessages()
-			},
-			GetSessionPath: func() string {
-				return kitInstance.GetSessionPath()
-			},
-			AppendEntry: func(entryType string, data string) (string, error) {
-				return kitInstance.Extensions().AppendEntry(entryType, data)
-			},
-			GetEntries: func(entryType string) []extensions.ExtensionEntry {
-				return kitInstance.Extensions().GetEntries(entryType)
-			},
-			SetEditorText: func(text string) {
-				appInstance.SetEditorTextFromExtension(text)
-			},
-			SetStatus: func(key string, text string, priority int) {
-				kitInstance.Extensions().SetStatus(extensions.StatusBarEntry{
-					Key:      key,
-					Text:     text,
-					Priority: priority,
-				})
-				go appInstance.NotifyWidgetUpdate()
-			},
-			RemoveStatus: func(key string) {
-				kitInstance.Extensions().RemoveStatus(key)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			GetOption: func(name string) string {
-				return kitInstance.Extensions().GetOption(name)
-			},
-			SetOption: func(name string, value string) {
-				kitInstance.Extensions().SetOption(name, value)
-			},
-			SetModel: func(modelString string) error {
-				// Capture previous model for the ModelChange event.
-				previousModel := kitInstance.Extensions().GetContext().Model
-				err := kitInstance.SetModel(context.Background(), modelString)
-				if err != nil {
-					return err
-				}
-				// Notify TUI so it updates model in status bar.
-				p, m, _ := models.ParseModelString(modelString)
-				appInstance.NotifyModelChanged(p, m)
-				// Update the context's Model field so handlers see it.
-				kitInstance.Extensions().UpdateContextModel(modelString)
-				// Fire OnModelChange event to extensions.
-				kitInstance.Extensions().EmitModelChange(modelString, previousModel, "extension")
-				// Update usage tracker with new model info for correct token counting.
-				if usageTracker != nil {
-					newProvider, newModel, _ := models.ParseModelString(modelString)
-					if newProvider != "unknown" && newModel != "unknown" && newProvider != "ollama" {
-						registry := models.GetGlobalRegistry()
-						if modelInfo := registry.LookupModel(newProvider, newModel); modelInfo != nil {
-							// Check OAuth status for Anthropic models
-							isOAuth := false
-							if newProvider == "anthropic" {
-								_, source, err := auth.GetAnthropicAPIKey(viper.GetString("provider-api-key"))
-								if err == nil && strings.HasPrefix(source, "stored OAuth") {
-									isOAuth = true
-								}
-							}
-							usageTracker.UpdateModelInfo(modelInfo, newProvider, isOAuth)
-						}
-					}
-				}
-				return nil
-			},
-			GetAvailableModels: func() []extensions.ModelInfoEntry {
-				return kitInstance.GetAvailableModels()
-			},
-			EmitCustomEvent: func(name string, data string) {
-				kitInstance.Extensions().EmitCustomEvent(name, data)
-			},
-			Complete: func(req extensions.CompleteRequest) (extensions.CompleteResponse, error) {
-				return kitInstance.ExecuteCompletion(context.Background(), req)
-			},
-			SuspendTUI: func(callback func()) error {
-				return appInstance.SuspendTUI(callback)
-			},
-			RenderMessage: func(rendererName, content string) {
-				renderer := kitInstance.Extensions().GetMessageRenderer(rendererName)
-				if renderer == nil || renderer.Render == nil {
-					appInstance.PrintFromExtension("", content)
-					return
-				}
-				w, _, _ := term.GetSize(int(os.Stdout.Fd()))
-				if w == 0 {
-					w = 80
-				}
-				rendered := renderer.Render(content, w)
-				appInstance.PrintFromExtension("", rendered)
-			},
-			ReloadExtensions: func() error {
-				err := kitInstance.Extensions().Reload()
-				if err != nil {
-					return err
-				}
-				// Notify TUI that widgets/status/commands may have changed.
-				go appInstance.NotifyWidgetUpdate()
-				return nil
-			},
-			GetAllTools: func() []extensions.ToolInfo {
-				return kitInstance.Extensions().GetToolInfos()
-			},
-			SetActiveTools: func(names []string) {
-				kitInstance.Extensions().SetActiveTools(names)
-			},
-			RegisterTheme: func(name string, config extensions.ThemeColorConfig) {
-				tc := func(c extensions.ThemeColor) [2]string { return [2]string{c.Light, c.Dark} }
-				ui.RegisterThemeFromConfig(name,
-					tc(config.Primary), tc(config.Secondary),
-					tc(config.Success), tc(config.Warning),
-					tc(config.Error), tc(config.Info),
-					tc(config.Text), tc(config.Muted),
-					tc(config.VeryMuted), tc(config.Background),
-					tc(config.Border), tc(config.MutedBorder),
-					tc(config.System), tc(config.Tool),
-					tc(config.Accent), tc(config.Highlight),
-					tc(config.MdHeading), tc(config.MdLink),
-					tc(config.MdKeyword), tc(config.MdString),
-					tc(config.MdNumber), tc(config.MdComment),
-				)
-			},
-			SetTheme: func(name string) error {
-				return ui.ApplyTheme(name)
-			},
-			ListThemes: func() []string {
-				return ui.ListThemes()
-			},
-			ShowOverlay: func(config extensions.OverlayConfig) extensions.OverlayResult {
-				ch := make(chan app.OverlayResponse, 1)
-				appInstance.SendOverlayRequest(app.OverlayRequestEvent{
-					Title:       config.Title,
-					Content:     config.Content.Text,
-					Markdown:    config.Content.Markdown,
-					BorderColor: config.Style.BorderColor,
-					Background:  config.Style.Background,
-					Width:       config.Width,
-					MaxHeight:   config.MaxHeight,
-					Anchor:      string(config.Anchor),
-					Actions:     config.Actions,
-					ResponseCh:  ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.OverlayResult{Cancelled: true, Index: -1}
-				}
-				return extensions.OverlayResult{
-					Action: resp.Action,
-					Index:  resp.Index,
-				}
-			},
-			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
-				// In-process subagent via SDK.
-				sdkCfg := kit.SubagentConfig{
-					Prompt:       config.Prompt,
-					Model:        config.Model,
-					SystemPrompt: config.SystemPrompt,
-					Timeout:      config.Timeout,
-					NoSession:    config.NoSession,
-				}
-				// Bridge SDK events to extension SubagentEvents.
-				if config.OnEvent != nil {
-					sdkCfg.OnEvent = func(e kit.Event) {
-						se := sdkEventToSubagentEvent(e)
-						if se.Type != "" {
-							config.OnEvent(se)
-						}
-					}
-				}
-				result, err := kitInstance.Subagent(ctx, sdkCfg)
-				if result == nil {
-					return nil, &extensions.SubagentResult{Error: err}, err
-				}
-				extResult := &extensions.SubagentResult{
-					Response:  result.Response,
-					Error:     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
-			},
-
-			// -------------------------------------------------------------------------
-			// Tree Navigation API (Phase 1 Bridge)
-			// -------------------------------------------------------------------------
-			GetTreeNode: func(entryID string) *extensions.TreeNode {
-				node := kitInstance.GetTreeNode(entryID)
-				if node == nil {
-					return nil
-				}
-				return &extensions.TreeNode{
-					ID:        node.ID,
-					ParentID:  node.ParentID,
-					Type:      node.Type,
-					Role:      node.Role,
-					Content:   node.Content,
-					Model:     node.Model,
-					Provider:  node.Provider,
-					Timestamp: node.Timestamp,
-					Children:  node.Children,
-				}
-			},
-			GetCurrentBranch: func() []extensions.TreeNode {
-				nodes := kitInstance.GetCurrentBranch()
-				result := make([]extensions.TreeNode, len(nodes))
-				for i, n := range nodes {
-					result[i] = extensions.TreeNode{
-						ID:        n.ID,
-						ParentID:  n.ParentID,
-						Type:      n.Type,
-						Role:      n.Role,
-						Content:   n.Content,
-						Model:     n.Model,
-						Provider:  n.Provider,
-						Timestamp: n.Timestamp,
-						Children:  n.Children,
-					}
-				}
-				return result
-			},
-			GetChildren: kitInstance.GetChildren,
-			NavigateTo: func(entryID string) extensions.TreeNavigationResult {
-				err := kitInstance.NavigateTo(entryID)
-				if err != nil {
-					return extensions.TreeNavigationResult{Success: false, Error: err.Error()}
-				}
-				return extensions.TreeNavigationResult{Success: true}
-			},
-			SummarizeBranch: func(fromID, toID string) string {
-				summary, _ := kitInstance.SummarizeBranch(fromID, toID)
-				return summary
-			},
-			CollapseBranch: func(fromID, toID, summary string) extensions.TreeNavigationResult {
-				err := kitInstance.CollapseBranch(fromID, toID, summary)
-				if err != nil {
-					return extensions.TreeNavigationResult{Success: false, Error: err.Error()}
-				}
-				return extensions.TreeNavigationResult{Success: true}
-			},
-
-			// -------------------------------------------------------------------------
-			// Skill Loading API (Phase 2 Bridge)
-			// -------------------------------------------------------------------------
-			LoadSkill: func(path string) (*extensions.Skill, string) {
-				s, err := kitInstance.LoadSkillForExtension(path)
-				return s, err
-			},
-			LoadSkillsFromDir: func(dir string) extensions.SkillLoadResult {
-				return kitInstance.LoadSkillsFromDirForExtension(dir)
-			},
-			DiscoverSkills: func() extensions.SkillLoadResult {
-				skills := kitInstance.DiscoverSkillsForExtension()
-				return extensions.SkillLoadResult{Skills: skills}
-			},
-			InjectSkillAsContext: func(skillName string) string {
-				// Find skill by name
-				skills := kitInstance.DiscoverSkillsForExtension()
-				for _, s := range skills {
-					if s.Name == skillName {
-						// Inject via SendMessage as a system context message
-						appInstance.Run(fmt.Sprintf("<skill name=%q>\n%s\n</skill>", s.Name, s.Content))
-						return ""
-					}
-				}
-				return fmt.Sprintf("skill not found: %s", skillName)
-			},
-			InjectRawSkillAsContext: func(path string) string {
-				s, err := kitInstance.LoadSkillForExtension(path)
-				if err != "" {
-					return err
-				}
-				appInstance.Run(fmt.Sprintf("<skill name=%q>\n%s\n</skill>", s.Name, s.Content))
-				return ""
-			},
-			GetAvailableSkills: kitInstance.DiscoverSkillsForExtension,
-
-			// -------------------------------------------------------------------------
-			// Template Parsing API (Phase 3 Bridge)
-			// -------------------------------------------------------------------------
-			ParseTemplate:        kit.ParseTemplate,
-			RenderTemplate:       kit.RenderTemplate,
-			ParseArguments:       kit.ParseArguments,
-			SimpleParseArguments: kit.SimpleParseArguments,
-			EvaluateModelConditional: func(condition string) bool {
-				return kit.EvaluateModelConditional(kitInstance.Extensions().GetContext().Model, condition)
-			},
-			RenderWithModelConditionals: func(content string) string {
-				return kit.RenderWithModelConditionals(content, kitInstance.Extensions().GetContext().Model)
-			},
-
-			// -------------------------------------------------------------------------
-			// Model Resolution API (Phase 4 Bridge)
-			// -------------------------------------------------------------------------
-			ResolveModelChain: kit.ResolveModelChain,
-			GetModelCapabilities: func(model string) (extensions.ModelCapabilities, string) {
-				return kit.GetModelCapabilities(model)
-			},
-			CheckModelAvailable: kit.CheckModelAvailable,
-			GetCurrentProvider: func() string {
-				return kit.GetCurrentProvider(kitInstance.Extensions().GetContext().Model)
-			},
-			GetCurrentModelID: func() string {
-				return kit.GetCurrentModelID(kitInstance.Extensions().GetContext().Model)
-			},
+		extCtx := buildInteractiveExtensionContext(extensionContextDeps{
+			ctx:          ctx,
+			cwd:          cwd,
+			modelName:    modelName,
+			interactive:  positionalPrompt == "",
+			kitInstance:  kitInstance,
+			appInstance:  appInstance,
+			usageTracker: usageTracker,
 		})
+		extCtx.Print = func(text string) {
+			// Capture messages during startup, print after startup banner.
+			startupExtensionMessages = append(startupExtensionMessages, text)
+		}
+		extCtx.PrintInfo = func(text string) {
+			startupExtensionMessages = append(startupExtensionMessages, text)
+		}
+		extCtx.PrintError = func(text string) {
+			startupExtensionMessages = append(startupExtensionMessages, text)
+		}
+		kitInstance.Extensions().SetContext(extCtx)
 		kitInstance.Extensions().EmitSessionStart()
 
 		// Restore normal print functions for runtime use.
-		kitInstance.Extensions().SetContext(extensions.Context{
-			CWD:           cwd,
-			Model:         modelName,
-			Interactive:   positionalPrompt == "",
-			Print:         func(text string) { appInstance.PrintFromExtension("", text) },
-			PrintInfo:     func(text string) { appInstance.PrintFromExtension("info", text) },
-			PrintError:    func(text string) { appInstance.PrintFromExtension("error", text) },
-			PrintBlock:    appInstance.PrintBlockFromExtension,
-			SendMessage:   func(text string) { appInstance.Run(text) },
-			CancelAndSend: func(text string) { appInstance.InterruptAndSend(text) },
-			Abort:         func() { appInstance.Abort() },
-			IsIdle:        func() bool { return !appInstance.IsBusy() },
-			Compact: func(cfg extensions.CompactConfig) error {
-				return appInstance.CompactAsync(cfg.CustomInstructions, cfg.OnComplete, cfg.OnError)
-			},
-			SendMultimodalMessage: func(text string, files []extensions.FilePart) {
-				parts := make([]kit.LLMFilePart, len(files))
-				for i, f := range files {
-					parts[i] = kit.LLMFilePart{
-						Filename:  f.Filename,
-						Data:      f.Data,
-						MediaType: f.MediaType,
-					}
-				}
-				appInstance.RunWithFiles(text, parts)
-			},
-			GetSessionUsage: func() extensions.SessionUsage {
-				if usageTracker == nil {
-					return extensions.SessionUsage{}
-				}
-				stats := usageTracker.GetSessionStats()
-				return extensions.SessionUsage{
-					TotalInputTokens:      stats.TotalInputTokens,
-					TotalOutputTokens:     stats.TotalOutputTokens,
-					TotalCacheReadTokens:  stats.TotalCacheReadTokens,
-					TotalCacheWriteTokens: stats.TotalCacheWriteTokens,
-					TotalCost:             stats.TotalCost,
-					RequestCount:          stats.RequestCount,
-				}
-			},
-			Exit: func() { appInstance.QuitFromExtension() },
-			SetWidget: func(config extensions.WidgetConfig) {
-				kitInstance.Extensions().SetWidget(config)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			RemoveWidget: func(id string) {
-				kitInstance.Extensions().RemoveWidget(id)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			SetHeader: func(config extensions.HeaderFooterConfig) {
-				kitInstance.Extensions().SetHeader(config)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			RemoveHeader: func() {
-				kitInstance.Extensions().RemoveHeader()
-				go appInstance.NotifyWidgetUpdate()
-			},
-			SetFooter: func(config extensions.HeaderFooterConfig) {
-				kitInstance.Extensions().SetFooter(config)
-				go appInstance.NotifyWidgetUpdate()
-			},
-			RemoveFooter: func() {
-				kitInstance.Extensions().RemoveFooter()
-				go appInstance.NotifyWidgetUpdate()
-			},
-			PromptSelect: func(config extensions.PromptSelectConfig) extensions.PromptSelectResult {
-				ch := make(chan app.PromptResponse, 1)
-				appInstance.SendPromptRequest(app.PromptRequestEvent{
-					PromptType: "select",
-					Message:    config.Message,
-					Options:    config.Options,
-					ResponseCh: ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.PromptSelectResult{Cancelled: true}
-				}
-				return extensions.PromptSelectResult{Value: resp.Value, Index: resp.Index}
-			},
-			PromptConfirm: func(config extensions.PromptConfirmConfig) extensions.PromptConfirmResult {
-				ch := make(chan app.PromptResponse, 1)
-				def := "false"
-				if config.DefaultValue {
-					def = "true"
-				}
-				appInstance.SendPromptRequest(app.PromptRequestEvent{
-					PromptType: "confirm",
-					Message:    config.Message,
-					Default:    def,
-					ResponseCh: ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.PromptConfirmResult{Cancelled: true}
-				}
-				return extensions.PromptConfirmResult{Value: resp.Confirmed}
-			},
-			PromptInput: func(config extensions.PromptInputConfig) extensions.PromptInputResult {
-				ch := make(chan app.PromptResponse, 1)
-				appInstance.SendPromptRequest(app.PromptRequestEvent{
-					PromptType:  "input",
-					Message:     config.Message,
-					Placeholder: config.Placeholder,
-					Default:     config.Default,
-					ResponseCh:  ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.PromptInputResult{Cancelled: true}
-				}
-				return extensions.PromptInputResult{Value: resp.Value}
-			},
-			ShowOverlay: func(config extensions.OverlayConfig) extensions.OverlayResult {
-				ch := make(chan app.OverlayResponse, 1)
-				appInstance.SendOverlayRequest(app.OverlayRequestEvent{
-					Title:       config.Title,
-					Content:     config.Content.Text,
-					Markdown:    config.Content.Markdown,
-					BorderColor: config.Style.BorderColor,
-					Background:  config.Style.Background,
-					Width:       config.Width,
-					MaxHeight:   config.MaxHeight,
-					Anchor:      string(config.Anchor),
-					Actions:     config.Actions,
-					ResponseCh:  ch,
-				})
-				resp := <-ch
-				if resp.Cancelled {
-					return extensions.OverlayResult{Cancelled: true, Index: -1}
-				}
-				return extensions.OverlayResult{
-					Action: resp.Action,
-					Index:  resp.Index,
-				}
-			},
-			SpawnSubagent: func(config extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
-				// In-process subagent via SDK.
-				sdkCfg := kit.SubagentConfig{
-					Prompt:       config.Prompt,
-					Model:        config.Model,
-					SystemPrompt: config.SystemPrompt,
-					Timeout:      config.Timeout,
-					NoSession:    config.NoSession,
-				}
-				// Bridge SDK events to extension SubagentEvents.
-				if config.OnEvent != nil {
-					sdkCfg.OnEvent = func(e kit.Event) {
-						se := sdkEventToSubagentEvent(e)
-						if se.Type != "" {
-							config.OnEvent(se)
-						}
-					}
-				}
-				result, err := kitInstance.Subagent(ctx, sdkCfg)
-				if result == nil {
-					return nil, &extensions.SubagentResult{Error: err}, err
-				}
-				extResult := &extensions.SubagentResult{
-					Response:  result.Response,
-					Error:     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
-			},
-
-			// -------------------------------------------------------------------------
-			// Tree Navigation API (Phase 1 Bridge) - Second Context
-			// -------------------------------------------------------------------------
-			GetTreeNode: func(entryID string) *extensions.TreeNode {
-				node := kitInstance.GetTreeNode(entryID)
-				if node == nil {
-					return nil
-				}
-				return &extensions.TreeNode{
-					ID:        node.ID,
-					ParentID:  node.ParentID,
-					Type:      node.Type,
-					Role:      node.Role,
-					Content:   node.Content,
-					Model:     node.Model,
-					Provider:  node.Provider,
-					Timestamp: node.Timestamp,
-					Children:  node.Children,
-				}
-			},
-			GetCurrentBranch: func() []extensions.TreeNode {
-				nodes := kitInstance.GetCurrentBranch()
-				result := make([]extensions.TreeNode, len(nodes))
-				for i, n := range nodes {
-					result[i] = extensions.TreeNode{
-						ID:        n.ID,
-						ParentID:  n.ParentID,
-						Type:      n.Type,
-						Role:      n.Role,
-						Content:   n.Content,
-						Model:     n.Model,
-						Provider:  n.Provider,
-						Timestamp: n.Timestamp,
-						Children:  n.Children,
-					}
-				}
-				return result
-			},
-			GetChildren: kitInstance.GetChildren,
-			NavigateTo: func(entryID string) extensions.TreeNavigationResult {
-				err := kitInstance.NavigateTo(entryID)
-				if err != nil {
-					return extensions.TreeNavigationResult{Success: false, Error: err.Error()}
-				}
-				return extensions.TreeNavigationResult{Success: true}
-			},
-			SummarizeBranch: func(fromID, toID string) string {
-				summary, _ := kitInstance.SummarizeBranch(fromID, toID)
-				return summary
-			},
-			CollapseBranch: func(fromID, toID, summary string) extensions.TreeNavigationResult {
-				err := kitInstance.CollapseBranch(fromID, toID, summary)
-				if err != nil {
-					return extensions.TreeNavigationResult{Success: false, Error: err.Error()}
-				}
-				return extensions.TreeNavigationResult{Success: true}
-			},
-
-			// -------------------------------------------------------------------------
-			// Skill Loading API (Phase 2 Bridge) - Second Context
-			// -------------------------------------------------------------------------
-			LoadSkill: func(path string) (*extensions.Skill, string) {
-				s, err := kitInstance.LoadSkillForExtension(path)
-				return s, err
-			},
-			LoadSkillsFromDir: func(dir string) extensions.SkillLoadResult {
-				return kitInstance.LoadSkillsFromDirForExtension(dir)
-			},
-			DiscoverSkills: func() extensions.SkillLoadResult {
-				skills := kitInstance.DiscoverSkillsForExtension()
-				return extensions.SkillLoadResult{Skills: skills}
-			},
-			InjectSkillAsContext: func(skillName string) string {
-				skills := kitInstance.DiscoverSkillsForExtension()
-				for _, s := range skills {
-					if s.Name == skillName {
-						appInstance.Run(fmt.Sprintf("<skill name=%q>\n%s\n</skill>", s.Name, s.Content))
-						return ""
-					}
-				}
-				return fmt.Sprintf("skill not found: %s", skillName)
-			},
-			InjectRawSkillAsContext: func(path string) string {
-				s, err := kitInstance.LoadSkillForExtension(path)
-				if err != "" {
-					return err
-				}
-				appInstance.Run(fmt.Sprintf("<skill name=%q>\n%s\n</skill>", s.Name, s.Content))
-				return ""
-			},
-			GetAvailableSkills: func() []extensions.Skill {
-				return kitInstance.DiscoverSkillsForExtension()
-			},
-
-			// -------------------------------------------------------------------------
-			// Template Parsing API (Phase 3 Bridge) - Second Context
-			// -------------------------------------------------------------------------
-			ParseTemplate:        kit.ParseTemplate,
-			RenderTemplate:       kit.RenderTemplate,
-			ParseArguments:       kit.ParseArguments,
-			SimpleParseArguments: kit.SimpleParseArguments,
-			EvaluateModelConditional: func(condition string) bool {
-				return kit.EvaluateModelConditional(kitInstance.Extensions().GetContext().Model, condition)
-			},
-			RenderWithModelConditionals: func(content string) string {
-				return kit.RenderWithModelConditionals(content, kitInstance.Extensions().GetContext().Model)
-			},
-
-			// -------------------------------------------------------------------------
-			// Model Resolution API (Phase 4 Bridge) - Second Context
-			// -------------------------------------------------------------------------
-			ResolveModelChain: kit.ResolveModelChain,
-			GetModelCapabilities: func(model string) (extensions.ModelCapabilities, string) {
-				return kit.GetModelCapabilities(model)
-			},
-			CheckModelAvailable: kit.CheckModelAvailable,
-			GetCurrentProvider: func() string {
-				return kit.GetCurrentProvider(kitInstance.Extensions().GetContext().Model)
-			},
-			GetCurrentModelID: func() string {
-				return kit.GetCurrentModelID(kitInstance.Extensions().GetContext().Model)
-			},
+		extCtx = buildInteractiveExtensionContext(extensionContextDeps{
+			ctx:          ctx,
+			cwd:          cwd,
+			modelName:    modelName,
+			interactive:  positionalPrompt == "",
+			kitInstance:  kitInstance,
+			appInstance:  appInstance,
+			usageTracker: usageTracker,
 		})
+		extCtx.Print = func(text string) { appInstance.PrintFromExtension("", text) }
+		extCtx.PrintInfo = func(text string) { appInstance.PrintFromExtension("info", text) }
+		extCtx.PrintError = func(text string) { appInstance.PrintFromExtension("error", text) }
+		kitInstance.Extensions().SetContext(extCtx)
 	}
 
 	// Convert extension commands to UI-layer type for the interactive TUI.
@@ -1642,9 +935,10 @@ func runNormalMode(ctx context.Context) error {
 			source = "project"
 		}
 		skillItems = append(skillItems, ui.SkillItem{
-			Name:   s.Name,
-			Path:   s.Path,
-			Source: source,
+			Name:        s.Name,
+			Path:        s.Path,
+			Source:      source,
+			Description: s.Description,
 		})
 	}
 
@@ -1683,9 +977,10 @@ func runNormalMode(ctx context.Context) error {
 				source = "project"
 			}
 			items = append(items, ui.SkillItem{
-				Name:   s.Name,
-				Path:   s.Path,
-				Source: source,
+				Name:        s.Name,
+				Path:        s.Path,
+				Source:      source,
+				Description: s.Description,
 			})
 		}
 		return items
@@ -2184,42 +1479,3 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 	_, runErr := program.Run()
 	return runErr
 }
-
-// sdkEventToSubagentEvent converts an SDK event to an extension-facing
-// SubagentEvent. Returns a zero-value event (Type=="") for events that
-// don't map to anything useful.
-func sdkEventToSubagentEvent(e kit.Event) extensions.SubagentEvent {
-	switch ev := e.(type) {
-	case kit.MessageUpdateEvent:
-		return extensions.SubagentEvent{Type: "text", Content: ev.Chunk}
-	case kit.ReasoningDeltaEvent:
-		return extensions.SubagentEvent{Type: "reasoning", Content: ev.Delta}
-	case kit.ToolCallEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_call", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind, ToolArgs: ev.ToolArgs,
-		}
-	case kit.ToolExecutionStartEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_execution_start", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
-		}
-	case kit.ToolExecutionEndEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_execution_end", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
-		}
-	case kit.ToolResultEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_result", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
-			ToolResult: ev.Result, IsError: ev.IsError,
-		}
-	case kit.TurnStartEvent:
-		return extensions.SubagentEvent{Type: "turn_start"}
-	case kit.TurnEndEvent:
-		return extensions.SubagentEvent{Type: "turn_end"}
-	default:
-		return extensions.SubagentEvent{}
-	}
-}

internal/acpserver/session.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/charmbracelet/log"
 
+	"github.com/mark3labs/kit/internal/extbridge"
 	"github.com/mark3labs/kit/internal/extensions"
 	kit "github.com/mark3labs/kit/pkg/kit"
 )
@@ -152,38 +153,7 @@ func (r *sessionRegistry) create(ctx context.Context, cwd string) (*acpSession,
 				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
+				return extbridge.SpawnSubagent(context.Background(), kitInstance, config)
 			},
 
 			// Render — fall back to logging.
@@ -269,40 +239,3 @@ func (s *acpSession) clearCancel() {
 	defer s.cancelMu.Unlock()
 	s.cancelFn = nil
 }
-
-// sdkEventToSubagentEvent converts an SDK event to an extension SubagentEvent.
-func sdkEventToSubagentEvent(e kit.Event) extensions.SubagentEvent {
-	switch ev := e.(type) {
-	case kit.MessageUpdateEvent:
-		return extensions.SubagentEvent{Type: "text", Content: ev.Chunk}
-	case kit.ReasoningDeltaEvent:
-		return extensions.SubagentEvent{Type: "reasoning", Content: ev.Delta}
-	case kit.ToolCallEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_call", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind, ToolArgs: ev.ToolArgs,
-		}
-	case kit.ToolExecutionStartEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_execution_start", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
-		}
-	case kit.ToolExecutionEndEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_execution_end", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
-		}
-	case kit.ToolResultEvent:
-		return extensions.SubagentEvent{
-			Type: "tool_result", ToolCallID: ev.ToolCallID,
-			ToolName: ev.ToolName, ToolKind: ev.ToolKind,
-			ToolResult: ev.Result, IsError: ev.IsError,
-		}
-	case kit.TurnStartEvent:
-		return extensions.SubagentEvent{Type: "turn_start"}
-	case kit.TurnEndEvent:
-		return extensions.SubagentEvent{Type: "turn_end"}
-	default:
-		return extensions.SubagentEvent{}
-	}
-}

internal/agent/mcp_adapter.go

@@ -9,12 +9,19 @@ import (
 	"github.com/mark3labs/kit/internal/tools"
 )
 
+// mcpExecutor is the subset of *tools.MCPToolManager that the adapter
+// actually uses. Extracted as an interface so the adapter is unit-testable
+// without constructing a full manager + connection pool.
+type mcpExecutor interface {
+	ExecuteTool(ctx context.Context, prefixedName, inputJSON string) (*tools.MCPToolResult, error)
+}
+
 // mcpAgentTool adapts an tools.MCPTool to the fantasy.AgentTool interface.
 // This keeps the fantasy dependency confined to the agent layer — the tools
 // package is a pure MCP client library with no LLM framework dependency.
 type mcpAgentTool struct {
 	tool            tools.MCPTool
-	manager         *tools.MCPToolManager
+	exec            mcpExecutor
 	providerOptions fantasy.ProviderOptions
 }
 
@@ -29,10 +36,26 @@ func (t *mcpAgentTool) Info() fantasy.ToolInfo {
 }
 
 // Run executes the MCP tool by delegating to the MCPToolManager.
+//
+// MCP-side failures (JSON-RPC protocol errors, transport failures, schema
+// validation rejections from the server) are surfaced to the model as soft
+// tool errors rather than escalated to a critical agent error. This matches
+// the contract that native Kit tools follow via kit.ErrorResult(...) and
+// lets the model self-correct (e.g. retry with a fixed argument shape) or
+// give up gracefully rather than aborting the turn mid-run.
+//
+// Context cancellation is the one exception: if the caller cancelled the
+// context the turn was aborted intentionally, so we propagate the ctx error
+// to let the agent loop unwind cleanly.
 func (t *mcpAgentTool) Run(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
-	result, err := t.manager.ExecuteTool(ctx, t.tool.Name, call.Input)
+	result, err := t.exec.ExecuteTool(ctx, t.tool.Name, call.Input)
 	if err != nil {
-		return fantasy.ToolResponse{}, fmt.Errorf("mcp tool execution failed: %w", err)
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return fantasy.ToolResponse{}, ctxErr
+		}
+		return fantasy.NewTextErrorResponse(
+			fmt.Sprintf("MCP tool %q failed: %s", t.tool.Name, err.Error()),
+		), nil
 	}
 
 	if result.IsError {
@@ -57,8 +80,8 @@ func mcpToolsToAgentTools(mcpTools []tools.MCPTool, manager *tools.MCPToolManage
 	agentTools := make([]fantasy.AgentTool, len(mcpTools))
 	for i, t := range mcpTools {
 		agentTools[i] = &mcpAgentTool{
-			tool:    t,
-			manager: manager,
+			tool: t,
+			exec: manager,
 		}
 	}
 	return agentTools

internal/agent/mcp_adapter_test.go

@@ -0,0 +1,158 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"charm.land/fantasy"
+
+	"github.com/mark3labs/kit/internal/tools"
+)
+
+// stubExecutor lets each test script the (result, err) pair returned by
+// ExecuteTool. The adapter holds an mcpExecutor interface, so this is the
+// only seam the tests need.
+type stubExecutor struct {
+	result *tools.MCPToolResult
+	err    error
+	// called records the last invocation for assertion.
+	called bool
+	name   string
+	input  string
+}
+
+func (s *stubExecutor) ExecuteTool(_ context.Context, prefixedName, inputJSON string) (*tools.MCPToolResult, error) {
+	s.called = true
+	s.name = prefixedName
+	s.input = inputJSON
+	return s.result, s.err
+}
+
+func newMCPAgentTool(exec mcpExecutor, name string) *mcpAgentTool {
+	return &mcpAgentTool{
+		tool: tools.MCPTool{Name: name},
+		exec: exec,
+	}
+}
+
+// Manager-side Go errors (JSON-RPC protocol errors, transport failures,
+// schema validation rejections from the MCP server) must be surfaced to
+// the model as soft tool errors so the agent loop can keep going. Aborting
+// the turn would discard all prior tool results — see issue #N.
+func TestMCPAgentTool_RPCErrorBecomesSoftError(t *testing.T) {
+	exec := &stubExecutor{
+		err: errors.New("MCP error -32602: Invalid params: missing field \"task\""),
+	}
+	tool := newMCPAgentTool(exec, "pubmed__search")
+
+	resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+		ID:    "call-1",
+		Name:  "pubmed__search",
+		Input: `{"query":"foo"}`,
+	})
+
+	if err != nil {
+		t.Fatalf("expected nil error (soft), got %v", err)
+	}
+	if !resp.IsError {
+		t.Fatalf("expected IsError=true, got false")
+	}
+	if !strings.Contains(resp.Content, "pubmed__search") {
+		t.Errorf("expected tool name in error content, got %q", resp.Content)
+	}
+	if !strings.Contains(resp.Content, "-32602") {
+		t.Errorf("expected underlying error text in content, got %q", resp.Content)
+	}
+}
+
+// Context cancellation is the one error that must remain critical: it
+// means the caller intentionally aborted, and the agent loop needs to
+// unwind cleanly rather than burning more steps.
+func TestMCPAgentTool_CtxCancelStaysCritical(t *testing.T) {
+	exec := &stubExecutor{
+		// Real managers typically return ctx.Err() (or a wrapper) when the
+		// context is cancelled mid-call.
+		err: context.Canceled,
+	}
+	tool := newMCPAgentTool(exec, "slow__tool")
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	resp, err := tool.Run(ctx, fantasy.ToolCall{Name: "slow__tool"})
+
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("expected context.Canceled, got %v", err)
+	}
+	if resp.IsError || resp.Content != "" {
+		t.Errorf("expected empty response on critical error, got IsError=%v Content=%q", resp.IsError, resp.Content)
+	}
+}
+
+// Deadline-exceeded behaves the same as cancellation: ctx.Err() is
+// non-nil, so the adapter must propagate the critical error rather than
+// converting the executor's error into a soft response.
+func TestMCPAgentTool_CtxDeadlineStaysCritical(t *testing.T) {
+	exec := &stubExecutor{err: context.DeadlineExceeded}
+	tool := newMCPAgentTool(exec, "slow__tool")
+
+	ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(-time.Second))
+	defer cancel()
+
+	resp, err := tool.Run(ctx, fantasy.ToolCall{Name: "slow__tool"})
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("expected context.DeadlineExceeded, got %v", err)
+	}
+	if resp.IsError || resp.Content != "" {
+		t.Errorf("expected empty response on critical error, got IsError=%v Content=%q", resp.IsError, resp.Content)
+	}
+}
+
+// Server-side soft errors (CallToolResult{ isError: true }) must continue
+// to flow through as soft errors — this was the existing behavior and
+// must not regress.
+func TestMCPAgentTool_ServerIsErrorRemainsSoftError(t *testing.T) {
+	exec := &stubExecutor{
+		result: &tools.MCPToolResult{
+			IsError: true,
+			Content: "search service is rate limited; try again in 30s",
+		},
+	}
+	tool := newMCPAgentTool(exec, "pubmed__search")
+
+	resp, err := tool.Run(context.Background(), fantasy.ToolCall{Name: "pubmed__search"})
+	if err != nil {
+		t.Fatalf("expected nil error, got %v", err)
+	}
+	if !resp.IsError {
+		t.Fatalf("expected IsError=true, got false")
+	}
+	if resp.Content != "search service is rate limited; try again in 30s" {
+		t.Errorf("expected pass-through content, got %q", resp.Content)
+	}
+}
+
+// Happy path: ordinary successful tool result is passed through unchanged.
+func TestMCPAgentTool_SuccessIsPassthrough(t *testing.T) {
+	exec := &stubExecutor{
+		result: &tools.MCPToolResult{
+			IsError: false,
+			Content: `{"hits":3}`,
+		},
+	}
+	tool := newMCPAgentTool(exec, "pubmed__search")
+
+	resp, err := tool.Run(context.Background(), fantasy.ToolCall{Name: "pubmed__search"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.IsError {
+		t.Fatalf("expected IsError=false")
+	}
+	if resp.Content != `{"hits":3}` {
+		t.Errorf("expected pass-through content, got %q", resp.Content)
+	}
+}

internal/app/app.go

@@ -78,6 +78,13 @@ type App struct {
 	// (~1 frame) so new updates are always let through once the TUI has had a
 	// chance to process the pending event.
 	widgetUpdatePending atomic.Bool
+
+	// steerDrainFn is the test seam used by releaseBusyAfterCompact to pull
+	// any steer messages that arrived during compaction. In production it is
+	// nil and the helper falls back to a.opts.Kit.DrainSteer(); tests that
+	// need to exercise the steer-drain path without standing up a full
+	// *kit.Kit can set this field directly to inject fake items.
+	steerDrainFn func() []queueItem
 }
 
 // New creates a new App with the provided options and pre-loaded messages.
@@ -356,6 +363,10 @@ func (a *App) AddContextMessage(text string) {
 // tea.Program. customInstructions is optional text appended to the summary
 // prompt (e.g. "Focus on the API design decisions").
 //
+// Any prompts queued via Run/RunWithFiles or steering messages injected via
+// Steer/SteerWithFiles while compaction is running are flushed automatically
+// once compaction completes (see releaseBusyAfterCompact).
+//
 // Satisfies ui.AppController.
 func (a *App) CompactConversation(customInstructions string) error {
 	a.mu.Lock()
@@ -377,11 +388,7 @@ func (a *App) CompactConversation(customInstructions string) error {
 
 	go func() {
 		defer a.wg.Done()
-		defer func() {
-			a.mu.Lock()
-			a.busy = false
-			a.mu.Unlock()
-		}()
+		defer a.releaseBusyAfterCompact()
 
 		// Subscribe to SDK events for streaming compaction summary to the TUI.
 		sendFn := func(msg tea.Msg) {
@@ -420,6 +427,9 @@ func (a *App) CompactConversation(customInstructions string) error {
 // CompactAsync is like CompactConversation but calls onComplete/onError
 // callbacks instead of sending TUI events. Used by the extension API's
 // ctx.Compact() which needs callback-based notification.
+//
+// Like CompactConversation, any prompts/steer messages received during
+// compaction are flushed automatically once compaction finishes.
 func (a *App) CompactAsync(customInstructions string, onComplete func(), onError func(string)) error {
 	a.mu.Lock()
 	if a.closed {
@@ -440,11 +450,7 @@ func (a *App) CompactAsync(customInstructions string, onComplete func(), onError
 
 	go func() {
 		defer a.wg.Done()
-		defer func() {
-			a.mu.Lock()
-			a.busy = false
-			a.mu.Unlock()
-		}()
+		defer a.releaseBusyAfterCompact()
 
 		// Subscribe to SDK events for streaming compaction summary to the TUI.
 		sendFn := func(msg tea.Msg) {
@@ -489,6 +495,81 @@ func (a *App) CompactAsync(customInstructions string, onComplete func(), onError
 	return nil
 }
 
+// releaseBusyAfterCompact is the deferred tail that runs at the end of every
+// compaction goroutine (success, error, or panic-after-recover paths). It
+// flips a.busy back to false, but before doing so it checks whether any
+// prompts piled up while compaction was running:
+//
+//   - Run/RunWithFiles append to a.queue when a.busy is set.
+//   - Steer/SteerWithFiles deposit messages into the SDK steer channel via
+//     Kit.InjectSteerWithFiles when a.busy is set.
+//
+// Without this hand-off the queue would sit idle until the user submits
+// another prompt — see issue #27. If we find anything pending we keep busy
+// set, splice the steer messages to the front of the queue, and start a
+// fresh drainQueue goroutine to deliver them as a single batched turn.
+func (a *App) releaseBusyAfterCompact() {
+	// Pull steer messages outside the app mutex; DrainSteer takes its own
+	// internal lock and we don't want to nest the two. The test seam
+	// (a.steerDrainFn) takes precedence so unit tests can inject fake
+	// steer items without a real *kit.Kit.
+	var steerItems []queueItem
+	switch {
+	case a.steerDrainFn != nil:
+		steerItems = a.steerDrainFn()
+	case a.opts.Kit != nil:
+		if leftover := a.opts.Kit.DrainSteer(); len(leftover) > 0 {
+			steerItems = make([]queueItem, len(leftover))
+			for i, sm := range leftover {
+				steerItems[i] = queueItem{Prompt: sm.Text, Files: sm.Files}
+			}
+		}
+	}
+
+	a.mu.Lock()
+	// If the app was closed while compaction was running, drop everything
+	// and just clear busy. Run/Steer would have rejected new items already
+	// after Close(), but this guards against in-flight items that slipped
+	// in just before closed was set.
+	if a.closed {
+		a.queue = a.queue[:0]
+		a.busy = false
+		a.mu.Unlock()
+		return
+	}
+
+	// Combine steer-channel items (front) with the in-memory queue (back).
+	// Steer messages are placed first so they retain their "act now"
+	// semantics relative to ordinary queued prompts that arrived later.
+	pending := append(steerItems, a.queue...)
+	a.queue = a.queue[:0]
+
+	if len(pending) == 0 {
+		a.busy = false
+		a.mu.Unlock()
+		return
+	}
+
+	// Hand off to drainQueue: it will pick up the first item directly and
+	// scoop the rest from a.queue on its first iteration.
+	first := pending[0]
+	if len(pending) > 1 {
+		a.queue = append(a.queue, pending[1:]...)
+	}
+	// Stay busy across the goroutine swap.
+	a.wg.Add(1)
+	a.mu.Unlock()
+
+	// Notify the UI that steer-channel messages were consumed so the
+	// steering badge can clear; ordinary queued prompts will be reflected
+	// by the QueueUpdatedEvent that drainQueue emits as it picks them up.
+	if len(steerItems) > 0 {
+		a.sendEvent(SteerConsumedEvent{})
+	}
+
+	go a.drainQueue(first)
+}
+
 // --------------------------------------------------------------------------
 // Non-interactive execution
 // --------------------------------------------------------------------------

internal/app/app_test.go

@@ -763,3 +763,209 @@ func TestFormatMaxTokensTruncatedMessage_NoKit(t *testing.T) {
 		}
 	}
 }
+
+// --------------------------------------------------------------------------
+// releaseBusyAfterCompact (issue #27)
+// --------------------------------------------------------------------------
+
+// TestReleaseBusyAfterCompact_flushesQueuedMessages is a regression test for
+// issue #27: messages queued via Run() while /compact is running used to sit
+// in a.queue indefinitely until the user typed another prompt. After the fix
+// the deferred releaseBusyAfterCompact tail picks up any pending items and
+// dispatches drainQueue automatically.
+//
+// We simulate the compaction completion path directly (bypassing the SDK)
+// by toggling busy=true, populating the queue exactly as Run() would have
+// during compaction, and then invoking releaseBusyAfterCompact.
+func TestReleaseBusyAfterCompact_flushesQueuedMessages(t *testing.T) {
+	stub := newStubWithFuncs(
+		func(ctx context.Context) (*kit.TurnResult, error) {
+			return turnResult("compacted then drained"), nil
+		},
+	)
+	app := newTestApp(stub)
+	defer app.Close()
+
+	// Simulate the state at the start of the compaction tail: busy is set
+	// and a couple of prompts have piled up in the queue while we were
+	// summarising. (Run() would have appended them and returned a queue
+	// length > 0 to the caller.)
+	app.mu.Lock()
+	app.busy = true
+	app.queue = append(app.queue,
+		queueItem{Prompt: "queued during compact #1"},
+		queueItem{Prompt: "queued during compact #2"},
+	)
+	app.mu.Unlock()
+
+	// Invoke the deferred tail directly. It should kick off drainQueue.
+	app.releaseBusyAfterCompact()
+
+	// drainQueue runs in a goroutine. Wait for the app to come back to idle.
+	ok := waitForCondition(2*time.Second, func() bool {
+		app.mu.Lock()
+		defer app.mu.Unlock()
+		return !app.busy
+	})
+	if !ok {
+		t.Fatal("app did not become idle after releaseBusyAfterCompact: queue not drained")
+	}
+
+	// Wait for any in-flight goroutine to finish before reading state.
+	app.wg.Wait()
+
+	if got := app.QueueLength(); got != 0 {
+		t.Fatalf("expected empty queue after drain, got %d", got)
+	}
+	if n := stub.callCount(); n == 0 {
+		t.Fatalf("expected stub PromptFunc to fire at least once after compact, got %d calls", n)
+	}
+}
+
+// TestReleaseBusyAfterCompact_idleWhenQueueEmpty verifies that with no
+// pending messages the helper just clears busy and does NOT spawn a
+// drainQueue goroutine (no spurious agent turn).
+func TestReleaseBusyAfterCompact_idleWhenQueueEmpty(t *testing.T) {
+	stub := newStub()
+	app := newTestApp(stub)
+	defer app.Close()
+
+	app.mu.Lock()
+	app.busy = true
+	app.mu.Unlock()
+
+	app.releaseBusyAfterCompact()
+
+	app.mu.Lock()
+	busy := app.busy
+	app.mu.Unlock()
+	if busy {
+		t.Fatal("expected busy=false after releaseBusyAfterCompact with empty queue")
+	}
+
+	// Give any rogue goroutine a moment to (incorrectly) call PromptFunc.
+	time.Sleep(50 * time.Millisecond)
+	if n := stub.callCount(); n != 0 {
+		t.Fatalf("expected 0 PromptFunc calls when queue empty, got %d", n)
+	}
+}
+
+// TestReleaseBusyAfterCompact_splicesSteerAheadOfQueue exercises the SDK
+// steer-drain branch of releaseBusyAfterCompact (issue #27 follow-up).
+//
+// Production wires a.opts.Kit.DrainSteer() to pull messages that arrived via
+// Steer/SteerWithFiles during compaction, but Options.Kit is *kit.Kit (a
+// concrete struct) so unit tests cannot stand up a real instance without a
+// full LLM backend. The test uses the unexported steerDrainFn seam to inject
+// fake steer items, then asserts that:
+//
+//   - Steer items are dispatched ahead of any prompts that piled up in
+//     a.queue (steer retains "act now" priority over ordinary queued
+//     prompts), and
+//   - the helper still hands off to drainQueue so the steer item actually
+//     fires (the previous behaviour left them stranded — see #27).
+func TestReleaseBusyAfterCompact_splicesSteerAheadOfQueue(t *testing.T) {
+	var pmu sync.Mutex
+	var firstPrompt string
+	stub := newStubWithFuncs(
+		func(ctx context.Context) (*kit.TurnResult, error) {
+			return turnResult("steer dispatched"), nil
+		},
+	)
+	// Wrap PromptFunc so we can capture the prompt text the stub receives
+	// (newStubWithFuncs's fns ignore prompt; we need it to verify ordering).
+	capturingPrompt := func(ctx context.Context, prompt string) (*kit.TurnResult, error) {
+		pmu.Lock()
+		if firstPrompt == "" {
+			firstPrompt = prompt
+		}
+		pmu.Unlock()
+		return stub.fn(ctx, prompt)
+	}
+	app := New(Options{PromptFunc: capturingPrompt}, nil)
+	defer app.Close()
+
+	// Inject fake steer items via the test seam. In production the same
+	// items would have been delivered through Kit.InjectSteerWithFiles
+	// during /compact and pulled by DrainSteer here.
+	app.steerDrainFn = func() []queueItem {
+		return []queueItem{
+			{Prompt: "steer-1"},
+			{Prompt: "steer-2"},
+		}
+	}
+
+	// Simulate the state at the end of compaction: busy is set and a couple
+	// of regular Run() prompts have piled up after the steer messages.
+	app.mu.Lock()
+	app.busy = true
+	app.queue = append(app.queue,
+		queueItem{Prompt: "queued-1"},
+		queueItem{Prompt: "queued-2"},
+	)
+	app.mu.Unlock()
+
+	app.releaseBusyAfterCompact()
+
+	// Wait for the dispatched batch to complete.
+	ok := waitForCondition(2*time.Second, func() bool {
+		app.mu.Lock()
+		defer app.mu.Unlock()
+		return !app.busy
+	})
+	if !ok {
+		t.Fatal("app did not become idle after steer-spliced releaseBusyAfterCompact")
+	}
+	app.wg.Wait()
+
+	// drainQueue picks up `first` directly and batches the rest. With
+	// PromptFunc set, executeBatch invokes us with items[0] only — that
+	// item must be the first steer message, proving steer items were
+	// spliced ahead of the previously queued prompts.
+	pmu.Lock()
+	got := firstPrompt
+	pmu.Unlock()
+	if got != "steer-1" {
+		t.Fatalf("expected first dispatched prompt to be steer item %q (steer items must come before queued prompts), got %q",
+			"steer-1", got)
+	}
+
+	// Queue should be fully drained and PromptFunc must have actually fired.
+	if n := app.QueueLength(); n != 0 {
+		t.Fatalf("expected empty queue after drain, got %d entries", n)
+	}
+	if n := stub.callCount(); n == 0 {
+		t.Fatal("expected stub PromptFunc to fire at least once after splice")
+	}
+}
+
+// TestReleaseBusyAfterCompact_dropsQueueWhenClosed verifies that if the app
+// was closed during compaction the helper discards any pending items rather
+// than spawning drainQueue against a torn-down App.
+func TestReleaseBusyAfterCompact_dropsQueueWhenClosed(t *testing.T) {
+	stub := newStub()
+	app := newTestApp(stub)
+
+	app.mu.Lock()
+	app.busy = true
+	app.queue = append(app.queue, queueItem{Prompt: "would have run"})
+	app.closed = true
+	app.mu.Unlock()
+
+	app.releaseBusyAfterCompact()
+
+	app.mu.Lock()
+	busy := app.busy
+	qLen := len(app.queue)
+	app.mu.Unlock()
+	if busy {
+		t.Fatal("expected busy=false even when closed")
+	}
+	if qLen != 0 {
+		t.Fatalf("expected queue cleared on closed app, got %d entries", qLen)
+	}
+	time.Sleep(20 * time.Millisecond)
+	if n := stub.callCount(); n != 0 {
+		t.Fatalf("expected 0 PromptFunc calls on closed app, got %d", n)
+	}
+}

internal/extbridge/extbridge.go

@@ -0,0 +1,97 @@
+// Package extbridge wires the public Kit SDK to the internal extensions
+// package. It exists so that cmd/ and internal/acpserver/ don't both
+// reimplement the same SDK→extension event/subagent conversions.
+package extbridge
+
+import (
+	"context"
+
+	"github.com/mark3labs/kit/internal/extensions"
+	kit "github.com/mark3labs/kit/pkg/kit"
+)
+
+// SDKEventToSubagentEvent converts an SDK [kit.Event] into the
+// extension-facing [extensions.SubagentEvent]. Returns a zero-value event
+// (Type=="") for events that don't map to anything useful — callers should
+// drop those.
+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{}
+	}
+}
+
+// SpawnSubagent runs a subagent in-process via the Kit SDK and translates
+// the result/events back into the extension-facing types. The returned
+// handle is always nil — the SDK path runs synchronously and does not
+// expose a separate process handle. Callers that need non-blocking
+// behaviour should run this in their own goroutine.
+//
+// This function consolidates the previously-duplicated wiring in
+// cmd/root.go (interactive + runtime contexts) and
+// internal/acpserver/session.go.
+func SpawnSubagent(ctx context.Context, k *kit.Kit, cfg extensions.SubagentConfig) (*extensions.SubagentHandle, *extensions.SubagentResult, error) {
+	sdkCfg := kit.SubagentConfig{
+		Prompt:       cfg.Prompt,
+		Model:        cfg.Model,
+		SystemPrompt: cfg.SystemPrompt,
+		Timeout:      cfg.Timeout,
+		NoSession:    cfg.NoSession,
+	}
+	if cfg.OnEvent != nil {
+		sdkCfg.OnEvent = func(e kit.Event) {
+			se := SDKEventToSubagentEvent(e)
+			if se.Type != "" {
+				cfg.OnEvent(se)
+			}
+		}
+	}
+
+	result, err := k.Subagent(ctx, 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
+}

internal/extensions/installer.go

@@ -450,25 +450,6 @@ func globalGitInstallRoot() string {
 	return filepath.Join(base, "kit", "git")
 }
 
-// GetInstalledPackages returns all installed packages from both scopes.
-func (i *Installer) GetInstalledPackages() ([]ManifestEntry, error) {
-	var all []ManifestEntry
-
-	global, err := i.loadManifest(ScopeGlobal)
-	if err != nil {
-		return nil, fmt.Errorf("loading global manifest: %w", err)
-	}
-	all = append(all, global.Packages...)
-
-	project, err := i.loadManifest(ScopeProject)
-	if err != nil {
-		return nil, fmt.Errorf("loading project manifest: %w", err)
-	}
-	all = append(all, project.Packages...)
-
-	return all, nil
-}
-
 // IsInstalled checks if a package is installed in either scope.
 // Returns (scope, true) if installed, ("", false) otherwise.
 func (i *Installer) IsInstalled(source *GitSource) (InstallScope, bool) {

internal/extensions/installer_test.go

@@ -245,14 +245,21 @@ func TestManifestEntryIdentity(t *testing.T) {
 	}
 }
 
+// TestLoadAndSaveManifest exercises the live *Installer.loadManifest /
+// saveManifest round-trip against a temp directory, ensuring an absent
+// manifest loads as empty and a saved manifest reads back identically.
 func TestLoadAndSaveManifest(t *testing.T) {
 	tempDir := t.TempDir()
+	installer := &Installer{
+		projectGitRoot: tempDir,
+		globalGitRoot:  tempDir,
+	}
 	manifestPath := filepath.Join(tempDir, "packages.json")
 
 	// Test loading non-existent manifest
-	manifest, err := loadManifestFromPath(manifestPath)
+	manifest, err := installer.loadManifest(ScopeGlobal)
 	if err != nil {
-		t.Fatalf("loadManifestFromPath() error = %v", err)
+		t.Fatalf("loadManifest() error = %v", err)
 	}
 	if len(manifest.Packages) != 0 {
 		t.Errorf("Expected empty packages, got %d", len(manifest.Packages))
@@ -273,15 +280,20 @@ func TestLoadAndSaveManifest(t *testing.T) {
 	}
 
 	// Save it
-	err = saveManifestToPath(manifest, manifestPath)
+	err = installer.saveManifest(manifest, ScopeGlobal)
 	if err != nil {
-		t.Fatalf("saveManifestToPath() error = %v", err)
+		t.Fatalf("saveManifest() error = %v", err)
+	}
+
+	// Verify it was written to expected path
+	if _, err := os.Stat(manifestPath); err != nil {
+		t.Fatalf("manifest file not created: %v", err)
 	}
 
 	// Load it back
-	loaded, err := loadManifestFromPath(manifestPath)
+	loaded, err := installer.loadManifest(ScopeGlobal)
 	if err != nil {
-		t.Fatalf("loadManifestFromPath() error = %v", err)
+		t.Fatalf("loadManifest() error = %v", err)
 	}
 	if len(loaded.Packages) != 1 {
 		t.Errorf("Expected 1 package, got %d", len(loaded.Packages))
@@ -291,21 +303,15 @@ func TestLoadAndSaveManifest(t *testing.T) {
 	}
 }
 
+// TestAddAndRemoveFromManifest verifies that *Installer.addToManifest
+// followed by removeFromManifest leaves the manifest in its original
+// (empty) state, using a temp-directory installer scope.
 func TestAddAndRemoveFromManifest(t *testing.T) {
 	tempDir := t.TempDir()
-
-	// Set up environment for manifest path
-	if err := os.Setenv("XDG_DATA_HOME", tempDir); err != nil {
-		t.Fatalf("Setenv() error = %v", err)
+	installer := &Installer{
+		projectGitRoot: tempDir,
+		globalGitRoot:  tempDir,
 	}
-	defer func() {
-		if err := os.Unsetenv("XDG_DATA_HOME"); err != nil {
-			t.Logf("Unsetenv() error = %v", err)
-		}
-	}()
-
-	// The manifest path when XDG_DATA_HOME is set
-	manifestPath := filepath.Join(tempDir, "kit", "git", "packages.json")
 
 	// Add an entry
 	entry := ManifestEntry{
@@ -315,58 +321,51 @@ func TestAddAndRemoveFromManifest(t *testing.T) {
 		Scope:  ScopeGlobal,
 	}
 
-	err := addEntryToManifest(entry, ScopeGlobal)
-	if err != nil {
-		t.Fatalf("addEntryToManifest() error = %v", err)
+	if err := installer.addToManifest(entry, ScopeGlobal); err != nil {
+		t.Fatalf("addToManifest() error = %v", err)
 	}
 
 	// Verify it was added
-	manifest, err := loadManifestFromPath(manifestPath)
+	manifest, err := installer.loadManifest(ScopeGlobal)
 	if err != nil {
-		t.Fatalf("loadManifestFromPath() error = %v", err)
+		t.Fatalf("loadManifest() error = %v", err)
 	}
 	if len(manifest.Packages) != 1 {
 		t.Errorf("Expected 1 package, got %d", len(manifest.Packages))
 	}
 
 	// Remove it
-	err = removeEntryFromManifest("github.com/user/repo", ScopeGlobal)
-	if err != nil {
-		t.Fatalf("removeEntryFromManifest() error = %v", err)
+	if err := installer.removeFromManifest("github.com/user/repo", ScopeGlobal); err != nil {
+		t.Fatalf("removeFromManifest() error = %v", err)
 	}
 
 	// Verify it was removed
-	manifest, err = loadManifestFromPath(manifestPath)
+	manifest, err = installer.loadManifest(ScopeGlobal)
 	if err != nil {
-		t.Fatalf("loadManifestFromPath() error = %v", err)
+		t.Fatalf("loadManifest() error = %v", err)
 	}
 	if len(manifest.Packages) != 0 {
 		t.Errorf("Expected 0 packages, got %d", len(manifest.Packages))
 	}
 }
 
+// TestFindInManifest writes a manifest file directly to the path
+// resolved by the package-level manifestPathForScope helper and then
+// confirms FindInManifest locates the entry by identity (and returns
+// nil for a non-existent identity).
 func TestFindInManifest(t *testing.T) {
 	tempDir := t.TempDir()
-	if err := os.Setenv("XDG_DATA_HOME", tempDir); err != nil {
-		t.Fatalf("Setenv() error = %v", err)
-	}
-	defer func() {
-		if err := os.Unsetenv("XDG_DATA_HOME"); err != nil {
-			t.Logf("Unsetenv() error = %v", err)
-		}
-	}()
+	t.Setenv("XDG_DATA_HOME", tempDir)
 
-	// Add an entry to global manifest
-	entry := ManifestEntry{
-		Source: "git:github.com/user/repo",
-		Host:   "github.com",
-		Path:   "user/repo",
-		Scope:  ScopeGlobal,
+	// Write a manifest entry directly via the package-level path resolver
+	// so FindInManifest (which uses manifestPathForScope) can read it back.
+	manifestPath := manifestPathForScope(ScopeGlobal)
+	if err := os.MkdirAll(filepath.Dir(manifestPath), 0755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
 	}
-
-	err := addEntryToManifest(entry, ScopeGlobal)
-	if err != nil {
-		t.Fatalf("addEntryToManifest() error = %v", err)
+	data := []byte(`{"packages":[{"source":"git:github.com/user/repo","repo":"","host":"github.com","path":"user/repo","pinned":false,"scope":"global","installed":"0001-01-01T00:00:00Z"}]}`)
+	if err := os.WriteFile(manifestPath, data, 0644); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
 	}
 
 	// Find it

internal/extensions/manifest.go

@@ -72,30 +72,6 @@ func loadManifestFromPath(path string) (*Manifest, error) {
 	return &manifest, nil
 }
 
-// saveManifestToScope saves the manifest to the given scope.
-func saveManifestToScope(manifest *Manifest, scope InstallScope) error {
-	path := manifestPathForScope(scope)
-	return saveManifestToPath(manifest, path)
-}
-
-// saveManifestToPath saves a manifest to a specific file path.
-func saveManifestToPath(manifest *Manifest, path string) error {
-	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
-		return fmt.Errorf("creating manifest directory: %w", err)
-	}
-
-	data, err := json.MarshalIndent(manifest, "", "  ")
-	if err != nil {
-		return fmt.Errorf("encoding manifest: %w", err)
-	}
-
-	if err := os.WriteFile(path, data, 0644); err != nil {
-		return fmt.Errorf("writing manifest: %w", err)
-	}
-
-	return nil
-}
-
 // manifestPathForScope returns the manifest file path for a scope.
 func manifestPathForScope(scope InstallScope) string {
 	if scope == ScopeProject {
@@ -113,55 +89,6 @@ func manifestPathForScope(scope InstallScope) string {
 	return filepath.Join(base, "kit", "git", "packages.json")
 }
 
-// GetGlobalManifest returns the global manifest.
-func GetGlobalManifest() (*Manifest, error) {
-	return loadManifestFromScope(ScopeGlobal)
-}
-
-// GetProjectManifest returns the project manifest.
-func GetProjectManifest() (*Manifest, error) {
-	return loadManifestFromScope(ScopeProject)
-}
-
-// addEntryToManifest adds or replaces an entry in the manifest for a scope.
-func addEntryToManifest(entry ManifestEntry, scope InstallScope) error {
-	manifest, err := loadManifestFromScope(scope)
-	if err != nil {
-		return err
-	}
-
-	// Remove any existing entry with same identity
-	identity := entry.Identity()
-	filtered := make([]ManifestEntry, 0, len(manifest.Packages))
-	for _, p := range manifest.Packages {
-		if p.Identity() != identity {
-			filtered = append(filtered, p)
-		}
-	}
-	filtered = append(filtered, entry)
-	manifest.Packages = filtered
-
-	return saveManifestToScope(manifest, scope)
-}
-
-// removeEntryFromManifest removes an entry by identity from the manifest for a scope.
-func removeEntryFromManifest(identity string, scope InstallScope) error {
-	manifest, err := loadManifestFromScope(scope)
-	if err != nil {
-		return err
-	}
-
-	filtered := make([]ManifestEntry, 0, len(manifest.Packages))
-	for _, p := range manifest.Packages {
-		if p.Identity() != identity {
-			filtered = append(filtered, p)
-		}
-	}
-	manifest.Packages = filtered
-
-	return saveManifestToScope(manifest, scope)
-}
-
 // FindInManifest finds an entry by identity in either global or project manifest.
 // Returns the entry and its scope, or nil if not found.
 func FindInManifest(identity string) (*ManifestEntry, InstallScope, error) {

internal/extensions/subagent.go

@@ -2,22 +2,15 @@
 package extensions
 
 import (
-	"bufio"
-	"context"
-	"encoding/json"
 	"fmt"
 	"os"
-	"os/exec"
-	"strings"
 	"sync"
-	"sync/atomic"
 	"time"
 )
 
 // ---------------------------------------------------------------------------
 // Subagent types
 // ---------------------------------------------------------------------------
-
 // SubagentConfig configures a subagent spawn.
 type SubagentConfig struct {
 	// Prompt is the task/instruction for the subagent (required).
@@ -157,221 +150,3 @@ func (h *SubagentHandle) Wait() SubagentResult {
 func (h *SubagentHandle) Done() <-chan struct{} {
 	return h.done
 }
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-// subagentJSONOutput matches the JSON envelope produced by `kit --json`.
-type subagentJSONOutput struct {
-	Response   string `json:"response"`
-	StopReason string `json:"stop_reason,omitempty"`
-	SessionID  string `json:"session_id,omitempty"`
-	Usage      *struct {
-		InputTokens  int64 `json:"input_tokens"`
-		OutputTokens int64 `json:"output_tokens"`
-	} `json:"usage,omitempty"`
-}
-
-var subagentCounter atomic.Uint64
-
-func generateSubagentID() string {
-	n := subagentCounter.Add(1)
-	return fmt.Sprintf("sub-%d-%d", time.Now().UnixNano(), n)
-}
-
-func findKitBinary() string {
-	// Try the current process executable first.
-	if exe, err := os.Executable(); err == nil {
-		if _, err := os.Stat(exe); err == nil {
-			return exe
-		}
-	}
-	// Fall back to PATH lookup.
-	if p, err := exec.LookPath("kit"); err == nil {
-		return p
-	}
-	return "kit"
-}
-
-// ---------------------------------------------------------------------------
-// SpawnSubagent implementation
-// ---------------------------------------------------------------------------
-
-// SpawnSubagent spawns a child Kit instance to perform a task.
-//
-// When config.Blocking is true, blocks until completion and returns the result
-// directly (handle is nil). When false, returns immediately with a handle for
-// monitoring/cancellation.
-//
-// The subagent runs with --json --no-session --no-extensions flags by default,
-// ensuring isolation from the parent's extensions and session state.
-func SpawnSubagent(cfg SubagentConfig) (*SubagentHandle, *SubagentResult, error) {
-	if cfg.Prompt == "" {
-		return nil, nil, fmt.Errorf("prompt is required")
-	}
-
-	timeout := cfg.Timeout
-	if timeout == 0 {
-		timeout = 5 * time.Minute
-	}
-
-	kitBinary := findKitBinary()
-
-	// Build subprocess arguments.
-	args := []string{
-		"--json",
-		"--no-extensions",
-	}
-	if cfg.NoSession {
-		args = append(args, "--no-session")
-	}
-	if cfg.Model != "" {
-		args = append(args, "--model", cfg.Model)
-	}
-
-	// Handle system prompt - write to temp file if provided.
-	var tmpFile *os.File
-	if cfg.SystemPrompt != "" {
-		var err error
-		tmpFile, err = os.CreateTemp("", "kit-subagent-*.txt")
-		if err != nil {
-			return nil, nil, fmt.Errorf("create temp file: %w", err)
-		}
-		if _, err := tmpFile.WriteString(cfg.SystemPrompt); err != nil {
-			_ = tmpFile.Close()
-			_ = os.Remove(tmpFile.Name())
-			return nil, nil, fmt.Errorf("write system prompt: %w", err)
-		}
-		_ = tmpFile.Close()
-		args = append(args, "--system-prompt", tmpFile.Name())
-	}
-
-	// Add the prompt as a positional argument.
-	args = append(args, cfg.Prompt)
-
-	// Create command with timeout context.
-	ctx, cancel := context.WithTimeout(context.Background(), timeout)
-
-	cmd := exec.CommandContext(ctx, kitBinary, args...)
-	cmd.Env = os.Environ()
-
-	stdout, err := cmd.StdoutPipe()
-	if err != nil {
-		cancel()
-		if tmpFile != nil {
-			_ = os.Remove(tmpFile.Name())
-		}
-		return nil, nil, fmt.Errorf("stdout pipe: %w", err)
-	}
-	stderr, err := cmd.StderrPipe()
-	if err != nil {
-		cancel()
-		if tmpFile != nil {
-			_ = os.Remove(tmpFile.Name())
-		}
-		return nil, nil, fmt.Errorf("stderr pipe: %w", err)
-	}
-
-	handle := &SubagentHandle{
-		ID:   generateSubagentID(),
-		done: make(chan struct{}),
-	}
-
-	// Start the subprocess.
-	start := time.Now()
-	if err := cmd.Start(); err != nil {
-		cancel()
-		if tmpFile != nil {
-			_ = os.Remove(tmpFile.Name())
-		}
-		return nil, nil, fmt.Errorf("start subprocess: %w", err)
-	}
-
-	handle.mu.Lock()
-	handle.proc = cmd.Process
-	handle.mu.Unlock()
-
-	// Run the subprocess monitoring in a goroutine.
-	go func() {
-		defer close(handle.done)
-		defer cancel()
-		if tmpFile != nil {
-			defer func() { _ = os.Remove(tmpFile.Name()) }()
-		}
-
-		var wg sync.WaitGroup
-		var stdoutBuf strings.Builder
-
-		// Read stderr (live output).
-		wg.Go(func() {
-			scanner := bufio.NewScanner(stderr)
-			scanner.Buffer(make([]byte, 256*1024), 256*1024)
-			for scanner.Scan() {
-				line := scanner.Text()
-				if cfg.OnOutput != nil && strings.TrimSpace(line) != "" {
-					cfg.OnOutput(line + "\n")
-				}
-			}
-		})
-
-		// Read stdout (JSON output).
-		scanner := bufio.NewScanner(stdout)
-		scanner.Buffer(make([]byte, 256*1024), 256*1024)
-		for scanner.Scan() {
-			stdoutBuf.WriteString(scanner.Text() + "\n")
-		}
-
-		wg.Wait()
-		waitErr := cmd.Wait()
-		elapsed := time.Since(start)
-
-		// Build result.
-		result := SubagentResult{Elapsed: elapsed}
-		if waitErr != nil {
-			result.Error = waitErr
-			if exitErr, ok := waitErr.(*exec.ExitError); ok {
-				result.ExitCode = exitErr.ExitCode()
-			} else {
-				result.ExitCode = 1
-			}
-		}
-
-		// Parse JSON output.
-		raw := strings.TrimSpace(stdoutBuf.String())
-		var parsed subagentJSONOutput
-		if raw != "" && json.Unmarshal([]byte(raw), &parsed) == nil {
-			result.Response = parsed.Response
-			result.SessionID = parsed.SessionID
-			if parsed.Usage != nil {
-				result.Usage = &SubagentUsage{
-					InputTokens:  parsed.Usage.InputTokens,
-					OutputTokens: parsed.Usage.OutputTokens,
-				}
-			}
-		} else {
-			// Fallback: use raw stdout.
-			result.Response = raw
-		}
-
-		handle.mu.Lock()
-		handle.result = &result
-		handle.proc = nil
-		handle.mu.Unlock()
-
-		if cfg.OnComplete != nil {
-			cfg.OnComplete(result)
-		}
-	}()
-
-	if cfg.Blocking {
-		// Wait for completion and return result directly.
-		<-handle.done
-		handle.mu.Lock()
-		r := handle.result
-		handle.mu.Unlock()
-		return nil, r, nil
-	}
-
-	return handle, nil, nil
-}

internal/models/cache_options.go

@@ -3,7 +3,6 @@ package models
 import (
 	"crypto/sha256"
 	"encoding/hex"
-	"maps"
 	"os"
 
 	"charm.land/fantasy"
@@ -69,19 +68,3 @@ func generateCacheKey(systemPrompt, modelID string) string {
 	// Prefix with "kit-" to identify KIT-generated cache keys
 	return "kit-" + hex.EncodeToString(h.Sum(nil))[:24]
 }
-
-// mergeProviderOptions merges multiple ProviderOptions maps.
-// Later maps take precedence over earlier ones.
-func mergeProviderOptions(opts ...fantasy.ProviderOptions) fantasy.ProviderOptions {
-	result := make(fantasy.ProviderOptions)
-
-	for _, opt := range opts {
-		maps.Copy(result, opt)
-	}
-
-	if len(result) == 0 {
-		return nil
-	}
-
-	return result
-}

internal/models/cache_options_test.go

@@ -3,8 +3,6 @@ package models
 import (
 	"os"
 	"testing"
-
-	"charm.land/fantasy"
 )
 
 func TestModelInfo_SupportsCaching(t *testing.T) {
@@ -192,57 +190,3 @@ func TestCachingPriorityOverThinking(t *testing.T) {
 		t.Errorf("OpenAI caching should work when thinking is OFF")
 	}
 }
-
-func TestMergeProviderOptions(t *testing.T) {
-	opts1 := fantasy.ProviderOptions{
-		"provider1": &testProviderData{value: "value1"},
-	}
-	opts2 := fantasy.ProviderOptions{
-		"provider2": &testProviderData{value: "value2"},
-	}
-
-	merged := mergeProviderOptions(opts1, opts2)
-
-	if len(merged) != 2 {
-		t.Errorf("mergeProviderOptions should combine options from multiple maps, got %d items", len(merged))
-	}
-
-	if _, ok := merged["provider1"]; !ok {
-		t.Errorf("merged options should contain 'provider1' key")
-	}
-
-	if _, ok := merged["provider2"]; !ok {
-		t.Errorf("merged options should contain 'provider2' key")
-	}
-
-	// Later options should override earlier ones
-	opts3 := fantasy.ProviderOptions{
-		"provider1": &testProviderData{value: "overridden"},
-	}
-	merged2 := mergeProviderOptions(opts1, opts3)
-
-	if data, ok := merged2["provider1"].(*testProviderData); ok {
-		if data.value != "overridden" {
-			t.Errorf("later options should override earlier ones, got %q", data.value)
-		}
-	}
-
-	if mergeProviderOptions() != nil {
-		t.Errorf("mergeProviderOptions with no args should return nil")
-	}
-}
-
-// testProviderData is a simple implementation of ProviderOptionsData for testing
-type testProviderData struct {
-	value string
-}
-
-func (t *testProviderData) Options() {}
-
-func (t *testProviderData) MarshalJSON() ([]byte, error) {
-	return []byte(`"` + t.value + `"`), nil
-}
-
-func (t *testProviderData) UnmarshalJSON(data []byte) error {
-	return nil
-}

internal/models/pool.go

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

internal/prompts/loader.go

@@ -179,31 +179,6 @@ func LoadFromDir(dir string) ([]*PromptTemplate, error) {
 	return templates, nil
 }
 
-// Deduplicate removes duplicate templates by name, keeping the first occurrence.
-// It returns the deduplicated list and diagnostics for any collisions.
-// This is a standalone function for when you need to deduplicate an existing list.
-func Deduplicate(templates []*PromptTemplate) ([]*PromptTemplate, []Diagnostic) {
-	seen := make(map[string]*PromptTemplate)
-	var result []*PromptTemplate
-	var diagnostics []Diagnostic
-
-	for _, tpl := range templates {
-		if existing, ok := seen[tpl.Name]; ok {
-			diagnostics = append(diagnostics, Diagnostic{
-				Name:        tpl.Name,
-				KeptPath:    existing.FilePath,
-				DroppedPath: tpl.FilePath,
-				Reason:      "duplicate template name (first-match-wins)",
-			})
-		} else {
-			seen[tpl.Name] = tpl
-			result = append(result, tpl)
-		}
-	}
-
-	return result, diagnostics
-}
-
 // loadDefaultTemplates returns the built-in default templates.
 // These are embedded templates that ship with Kit.
 func loadDefaultTemplates() []*PromptTemplate {

internal/session/session_dir_test.go

@@ -0,0 +1,70 @@
+package session
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestEncodeCwdForDir verifies the working-directory → session-directory
+// name encoding strips characters that are illegal on Windows (notably the
+// drive-letter colon, see issue #18) while preserving the previous output
+// for the typical Unix paths.
+func TestEncodeCwdForDir(t *testing.T) {
+	tests := []struct {
+		name string
+		cwd  string
+		want string
+	}{
+		{
+			name: "unix absolute path",
+			cwd:  "/home/user/proj",
+			want: "home--user--proj",
+		},
+		{
+			name: "unix relative path",
+			cwd:  "proj/sub",
+			want: "proj--sub",
+		},
+		{
+			name: "windows drive root",
+			cwd:  `C:\test`,
+			want: "C--test",
+		},
+		{
+			name: "windows nested path",
+			cwd:  `C:\Users\User\code`,
+			want: "C--Users--User--code",
+		},
+		{
+			name: "windows secondary drive",
+			cwd:  `S:\work\repo`,
+			want: "S--work--repo",
+		},
+		{
+			name: "windows mixed separators",
+			cwd:  `C:\Users/User\code`,
+			want: "C--Users--User--code",
+		},
+		{
+			name: "windows other illegal chars stripped",
+			cwd:  `C:\a<b>c|d?e*f"g`,
+			want: "C--abcdefg",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := encodeCwdForDir(tc.cwd)
+			if got != tc.want {
+				t.Errorf("encodeCwdForDir(%q) = %q, want %q", tc.cwd, got, tc.want)
+			}
+			// Encoded directory must never contain characters that are
+			// illegal in Windows directory names.
+			for _, bad := range []string{":", "<", ">", "\"", "|", "?", "*", "\\", "/"} {
+				if strings.Contains(got, bad) {
+					t.Errorf("encodeCwdForDir(%q) = %q contains illegal char %q", tc.cwd, got, bad)
+				}
+			}
+		})
+	}
+}

internal/session/tree_manager.go

@@ -1350,15 +1350,44 @@ func (tm *TreeManager) buildTreeNodeDepth(id string, depth int, visited map[stri
 // --- Path conventions ---
 
 // DefaultSessionDir returns the default session storage directory for a cwd.
-// Convention: ~/.kit/sessions/--<cwd-path>--/
+// Convention: ~/.kit/sessions/<encoded-cwd>, where path separators are
+// encoded as "--" with no leading or trailing dashes — e.g.
+// /home/user/proj becomes home--user--proj. See encodeCwdForDir for the
+// full encoding rules (including Windows path handling).
 func DefaultSessionDir(cwd string) string {
 	home, err := os.UserHomeDir()
 	if err != nil {
 		home = "."
 	}
-	// Convert path separators to double dashes.
-	safeCwd := strings.ReplaceAll(cwd, string(filepath.Separator), "--")
+	return filepath.Join(home, ".kit", "sessions", encodeCwdForDir(cwd))
+}
+
+// encodeCwdForDir converts a working-directory path into a single, filesystem-
+// safe directory name. Path separators are replaced with double dashes and
+// characters that are illegal in Windows directory names — most importantly
+// the colon that follows the drive letter (e.g. `C:\foo` → `C--foo`) — are
+// stripped. The result is identical to the previous Unix-only encoding for
+// paths that do not contain such characters, so existing session directories
+// are preserved.
+func encodeCwdForDir(cwd string) string {
+	// Convert both `/` and `\` to double dashes so encoding is stable across
+	// platforms and remains correct on Windows where `filepath.Separator`
+	// would otherwise miss forward-slash style paths.
+	safeCwd := strings.ReplaceAll(cwd, "\\", "--")
+	safeCwd = strings.ReplaceAll(safeCwd, "/", "--")
 	// Remove leading separator replacement.
 	safeCwd = strings.TrimPrefix(safeCwd, "--")
-	return filepath.Join(home, ".kit", "sessions", safeCwd)
+	// Strip characters that are illegal in directory names on Windows
+	// (`< > : " | ? *`). On Unix these characters are legal but rare in
+	// practice; stripping them keeps the encoding portable.
+	replacer := strings.NewReplacer(
+		":", "",
+		"<", "",
+		">", "",
+		"\"", "",
+		"|", "",
+		"?", "",
+		"*", "",
+	)
+	return replacer.Replace(safeCwd)
 }

internal/ui/block_renderer.go

@@ -28,15 +28,6 @@ type blockRenderer struct {
 // renderingOption configures block rendering
 type renderingOption func(*blockRenderer)
 
-// WithFullWidth returns a renderingOption that configures the block renderer
-// to expand to the full available width of its container. When enabled, the
-// block will fill the entire horizontal space rather than sizing to its content.
-func WithFullWidth() renderingOption {
-	return func(c *blockRenderer) {
-		c.fullWidth = true
-	}
-}
-
 // WithNoBorder returns a renderingOption that disables all borders on the
 // block, rendering content with only padding.
 func WithNoBorder() renderingOption {
@@ -63,15 +54,6 @@ func WithBorderColor(c color.Color) renderingOption {
 	}
 }
 
-// WithMarginTop returns a renderingOption that sets the top margin
-// for the block. The margin is specified in number of lines and adds
-// vertical space above the block.
-func WithMarginTop(margin int) renderingOption {
-	return func(c *blockRenderer) {
-		c.marginTop = margin
-	}
-}
-
 // WithMarginBottom returns a renderingOption that sets the bottom margin
 // for the block. The margin is specified in number of lines and adds
 // vertical space below the block.
@@ -81,24 +63,6 @@ func WithMarginBottom(margin int) renderingOption {
 	}
 }
 
-// WithPaddingLeft returns a renderingOption that sets the left padding
-// for the block content. The padding is specified in number of characters
-// and adds horizontal space between the left border and the content.
-func WithPaddingLeft(padding int) renderingOption {
-	return func(c *blockRenderer) {
-		c.paddingLeft = padding
-	}
-}
-
-// WithPaddingRight returns a renderingOption that sets the right padding
-// for the block content. The padding is specified in number of characters
-// and adds horizontal space between the content and the right border.
-func WithPaddingRight(padding int) renderingOption {
-	return func(c *blockRenderer) {
-		c.paddingRight = padding
-	}
-}
-
 // WithPaddingTop returns a renderingOption that sets the top padding
 // for the block content. The padding is specified in number of lines
 // and adds vertical space between the top border and the content.
@@ -117,33 +81,6 @@ func WithPaddingBottom(padding int) renderingOption {
 	}
 }
 
-// WithBackground returns a renderingOption that sets the background color
-// for the entire block. The color parameter accepts any color.Color value,
-// typically a lipgloss hex color (e.g. lipgloss.Color("#1e1e2e")).
-func WithBackground(c color.Color) renderingOption {
-	return func(br *blockRenderer) {
-		br.background = &c
-	}
-}
-
-// WithForeground returns a renderingOption that overrides the default text
-// foreground color (theme.Text) for the block. Useful for muted or
-// de-emphasized content blocks.
-func WithForeground(c color.Color) renderingOption {
-	return func(br *blockRenderer) {
-		br.foreground = &c
-	}
-}
-
-// WithWidth returns a renderingOption that sets a specific width for the block
-// in characters. This overrides the default container width and allows precise
-// control over the block's horizontal dimensions.
-func WithWidth(width int) renderingOption {
-	return func(c *blockRenderer) {
-		c.width = width
-	}
-}
-
 // renderContentBlock renders content with configurable styling options
 func renderContentBlock(content string, containerWidth int, options ...renderingOption) string {
 	renderer := &blockRenderer{

internal/ui/cli.go

@@ -54,12 +54,6 @@ func (c *CLI) GetUsageTracker() *UsageTracker {
 	return c.usageTracker
 }
 
-// GetDebugLogger returns a CLIDebugLogger instance that routes debug output
-// through the CLI's rendering system for consistent message formatting and display.
-func (c *CLI) GetDebugLogger() *CLIDebugLogger {
-	return NewCLIDebugLogger(c)
-}
-
 // SetModelName updates the current AI model name being used in the conversation.
 // This name is displayed in message headers to indicate which model is responding.
 func (c *CLI) SetModelName(modelName string) {
@@ -87,13 +81,6 @@ func (c *CLI) DisplayUserMessage(message string) {
 	fmt.Println(c.renderer.RenderUserMessage(message, time.Now()).Content)
 }
 
-// DisplayAssistantMessage renders and displays an AI assistant's response message
-// with appropriate formatting. This method delegates to DisplayAssistantMessageWithModel
-// with an empty model name for backward compatibility.
-func (c *CLI) DisplayAssistantMessage(message string) error {
-	return c.DisplayAssistantMessageWithModel(message, "")
-}
-
 // DisplayAssistantMessageWithModel renders and displays an AI assistant's response
 // with the specified model name shown in the message header. The message is
 // formatted according to the current display mode and includes timestamp information.
@@ -149,12 +136,6 @@ func (c *CLI) DisplayExtensionBlock(text, borderColor, subtitle string) {
 	fmt.Println(rendered)
 }
 
-// DisplayCancellation displays a system message indicating that the current
-// AI generation has been cancelled by the user (typically via ESC key).
-func (c *CLI) DisplayCancellation() {
-	fmt.Println(c.renderer.RenderSystemMessage("Generation cancelled by user (ESC pressed)", time.Now()).Content)
-}
-
 // DisplayDebugMessage renders and displays a debug message if debug mode is enabled.
 // Debug messages are formatted distinctively and only shown when the CLI is
 // initialized with debug=true.

internal/ui/commands/commands.go

@@ -199,18 +199,6 @@ func GetCommandByName(name string) *SlashCommand {
 	return nil
 }
 
-// GetAllCommandNames returns a complete list of all command names and their aliases.
-// This is useful for command completion, validation, and help display. The returned
-// slice contains both primary command names and all alternative aliases.
-func GetAllCommandNames() []string {
-	var names []string
-	for _, cmd := range SlashCommands {
-		names = append(names, cmd.Name)
-		names = append(names, cmd.Aliases...)
-	}
-	return names
-}
-
 // ExtensionCommand is a slash command registered by an extension. Unlike
 // built-in SlashCommands whose execution is hardcoded in handleSlashCommand,
 // extension commands carry their own Execute callback.

internal/ui/debug_logger.go

@@ -1,79 +0,0 @@
-package ui
-
-import (
-	"fmt"
-	"strings"
-	"time"
-)
-
-// CLIDebugLogger implements the tools.DebugLogger interface using CLI rendering.
-// It provides debug logging functionality that integrates with the CLI's display
-// system, ensuring debug messages are properly formatted and displayed alongside
-// other conversation content.
-type CLIDebugLogger struct {
-	cli *CLI
-}
-
-// NewCLIDebugLogger creates and returns a new CLIDebugLogger instance that routes
-// debug output through the provided CLI instance. The logger will respect the CLI's
-// debug mode setting and display format preferences.
-func NewCLIDebugLogger(cli *CLI) *CLIDebugLogger {
-	return &CLIDebugLogger{cli: cli}
-}
-
-// LogDebug processes and displays a debug message through the CLI's rendering system.
-// Messages are formatted with appropriate emojis and tags based on their content type
-// (DEBUG, POOL, etc.) and only displayed when debug mode is enabled. The method handles
-// multi-line debug output and connection pool status messages with context-aware formatting.
-func (l *CLIDebugLogger) LogDebug(message string) {
-	if l.cli == nil || !l.cli.debug {
-		return
-	}
-
-	// Format the message to include all the debug info in a structured way
-	var formattedMessage string
-
-	// Check if this is a multi-line debug output (like connection info)
-	if strings.Contains(message, "[DEBUG]") || strings.Contains(message, "[POOL]") {
-		// Extract the tag and content
-		if after, ok := strings.CutPrefix(message, "[DEBUG]"); ok {
-			content := after
-			content = strings.TrimSpace(content)
-			formattedMessage = fmt.Sprintf("🔍 DEBUG: %s", content)
-		} else if after, ok := strings.CutPrefix(message, "[POOL]"); ok {
-			content := after
-			content = strings.TrimSpace(content)
-
-			// Add appropriate emoji based on the message content
-			if strings.Contains(content, "Creating new connection") {
-				formattedMessage = fmt.Sprintf("🆕 POOL: %s", content)
-			} else if strings.Contains(content, "Created connection") || strings.Contains(content, "Initialized") {
-				formattedMessage = fmt.Sprintf("✅ POOL: %s", content)
-			} else if strings.Contains(content, "Reusing") {
-				formattedMessage = fmt.Sprintf("🔄 POOL: %s", content)
-			} else if strings.Contains(content, "unhealthy") || strings.Contains(content, "failed") {
-				formattedMessage = fmt.Sprintf("❌ POOL: %s", content)
-			} else if strings.Contains(content, "closed") {
-				formattedMessage = fmt.Sprintf("🛑 POOL: %s", content)
-			} else if strings.Contains(content, "Failed to close") {
-				formattedMessage = fmt.Sprintf("⚠️ POOL: %s", content)
-			} else {
-				formattedMessage = fmt.Sprintf("🔍 POOL: %s", content)
-			}
-		} else {
-			formattedMessage = message
-		}
-	} else {
-		formattedMessage = message
-	}
-
-	// Use the CLI's debug message rendering
-	fmt.Println(l.cli.renderer.RenderDebugMessage(formattedMessage, time.Now()).Content)
-}
-
-// IsDebugEnabled checks whether debug logging is currently active. Returns true
-// if the CLI instance exists and has debug mode enabled, allowing callers to
-// conditionally perform expensive debug operations only when necessary.
-func (l *CLIDebugLogger) IsDebugEnabled() bool {
-	return l.cli != nil && l.cli.debug
-}

internal/ui/message_items.go

@@ -25,17 +25,6 @@ type TextMessageItem struct {
 	timestamp   time.Time
 }
 
-// NewTextMessageItem creates a new text message for the scrollback.
-// The content should be pre-rendered using MessageRenderer for proper styling.
-func NewTextMessageItem(id string, role string, content string) *TextMessageItem {
-	return &TextMessageItem{
-		id:        id,
-		role:      role,
-		content:   content,
-		timestamp: time.Now(),
-	}
-}
-
 // NewStyledMessageItem creates a message item with pre-rendered styled content.
 // This is the preferred way to create messages when you have styled content from MessageRenderer.
 func NewStyledMessageItem(id string, role string, rawContent string, preRendered string) *TextMessageItem {
@@ -316,57 +305,6 @@ func (m *StreamingBashOutputItem) MarkComplete() {
 }
 
 // --------------------------------------------------------------------------
-// SystemMessageItem - System messages (commands, info, errors)
-// --------------------------------------------------------------------------
-
-// SystemMessageItem represents a system message (commands, info, errors).
-type SystemMessageItem struct {
-	id           string
-	content      string
-	timestamp    time.Time
-	cachedRender string
-	cachedWidth  int
-}
-
-// NewSystemMessageItem creates a new system message for the scrollback.
-func NewSystemMessageItem(id, content string) *SystemMessageItem {
-	return &SystemMessageItem{
-		id:        id,
-		content:   content,
-		timestamp: time.Now(),
-	}
-}
-
-func (m *SystemMessageItem) ID() string {
-	return m.id
-}
-
-func (m *SystemMessageItem) Render(width int) string {
-	// Return cached render if width matches
-	if m.cachedWidth == width && m.cachedRender != "" {
-		return m.cachedRender
-	}
-
-	// Simple system message formatting
-	rendered := "│ " + strings.ReplaceAll(m.content, "\n", "\n│ ")
-
-	// Cache and return
-	m.cachedRender = rendered
-	m.cachedWidth = width
-	return rendered
-}
-
-func (m *SystemMessageItem) Height() int {
-	if m.cachedRender != "" {
-		return strings.Count(m.cachedRender, "\n") + 1
-	}
-	// Estimate
-	if m.cachedWidth > 0 {
-		return (len(m.content) / max(m.cachedWidth-10, 40)) + 3
-	}
-	return 3
-}
-
 // --------------------------------------------------------------------------
 // Helper: generateMessageID
 // --------------------------------------------------------------------------

internal/ui/model.go

@@ -129,9 +129,10 @@ type AppController interface {
 // SkillItem holds display metadata about a loaded skill for the startup
 // [Skills] section. Built by the CLI layer from the SDK's []*kit.Skill.
 type SkillItem struct {
-	Name   string // Skill name (e.g. "btca-cli").
-	Path   string // Absolute path to the skill file.
-	Source string // "project" or "user" (global).
+	Name        string // Skill name (e.g. "btca-cli").
+	Path        string // Absolute path to the skill file.
+	Source      string // "project" or "user" (global).
+	Description string // Short summary used in autocomplete and help.
 }
 
 // MCPPromptInfo describes an MCP prompt for display in the TUI (autocomplete,
@@ -912,6 +913,20 @@ func NewAppModel(appCtrl AppController, opts AppModelOptions) *AppModel {
 		}
 	}
 
+	// Merge skills into autocomplete as /skill:<name> commands. Skills accept
+	// optional trailing args, so HasArgs is true — Enter populates the input
+	// with "/skill:name " rather than auto-submitting.
+	if ic, ok := m.input.(*InputComponent); ok && len(opts.SkillItems) > 0 {
+		for _, s := range opts.SkillItems {
+			ic.commands = append(ic.commands, commands.SlashCommand{
+				Name:        "/skill:" + s.Name,
+				Description: formatSkillDescription(s),
+				Category:    "Skills",
+				HasArgs:     true,
+			})
+		}
+	}
+
 	// Merge MCP prompts into autocomplete as /<server>:<prompt> commands.
 	if ic, ok := m.input.(*InputComponent); ok && len(opts.MCPPrompts) > 0 {
 		for _, p := range opts.MCPPrompts {
@@ -3395,13 +3410,46 @@ func (m *AppModel) refreshPromptTemplates() {
 	}
 }
 
-// refreshSkillItems reloads skill items from the provider callback.
-// Called on ContentReloadEvent.
+// refreshSkillItems reloads skill items from the provider callback and
+// updates the autocomplete entries. Called on ContentReloadEvent.
 func (m *AppModel) refreshSkillItems() {
 	if m.getSkillItems == nil {
 		return
 	}
-	m.skillItems = m.getSkillItems()
+	newItems := m.getSkillItems()
+	m.skillItems = newItems
+
+	if ic, ok := m.input.(*InputComponent); ok {
+		// Remove old Skills commands and add fresh ones.
+		var kept []commands.SlashCommand
+		for _, sc := range ic.commands {
+			if sc.Category != "Skills" {
+				kept = append(kept, sc)
+			}
+		}
+		for _, s := range newItems {
+			kept = append(kept, commands.SlashCommand{
+				Name:        "/skill:" + s.Name,
+				Description: formatSkillDescription(s),
+				Category:    "Skills",
+				HasArgs:     true,
+			})
+		}
+		ic.commands = kept
+	}
+}
+
+// formatSkillDescription returns the autocomplete description for a skill,
+// prefixed with [project] or [user] so users can tell colliding names apart.
+func formatSkillDescription(s SkillItem) string {
+	prefix := "[user]"
+	if s.Source == "project" {
+		prefix = "[project]"
+	}
+	if s.Description == "" {
+		return prefix
+	}
+	return prefix + " " + s.Description
 }
 
 // refreshMCPPrompts reloads MCP prompts from the provider callback and

internal/ui/render/blocks.go

@@ -19,28 +19,7 @@ import (
 //   - @path/to/file.txt      (unquoted, no spaces)
 var fileTokenPattern = regexp.MustCompile(`@"[^"]+"|@[^\s]+`)
 
-// UserBlock renders a user message with herald Tip styling.
-// The width parameter controls line wrapping so long messages don't overflow.
-// Any @file tokens in the content are highlighted with the theme accent color.
-func UserBlock(content string, width int, ty *herald.Typography, theme style.Theme) string {
-	if strings.TrimSpace(content) == "" {
-		content = "(empty message)"
-	}
-
-	// Wrap content before passing to herald Alert so long lines break
-	// inside the alert box. Subtract 4 to account for the alert bar
-	// prefix ("│ ") and a small margin.
-	if width > 4 {
-		content = lipgloss.Wrap(content, width-4, "")
-	}
-
-	// Highlight @file tokens with accent color so file references are
-	// visually distinct from surrounding prompt text.
-	content = HighlightFileTokens(content, theme)
-
-	rendered := ty.Tip(content)
-	return styleMarginBottom(theme, rendered)
-}
+// UserBlock-related rendering helpers and herald typography.
 
 // HighlightFileTokens wraps @file tokens in the given text with the theme
 // accent color so they stand out visually in rendered user messages.
@@ -154,44 +133,6 @@ func ErrorBlock(errorMsg string, ty *herald.Typography, theme style.Theme) strin
 	return styleMarginBottom(theme, rendered)
 }
 
-// ToolBlock renders a tool execution result with header and body.
-func ToolBlock(displayName, params, body string, isError bool, width int, ty *herald.Typography, theme style.Theme) string {
-	var icon string
-	iconColor := theme.Success
-	if isError {
-		icon = "×"
-		iconColor = theme.Error
-	} else {
-		icon = "✓"
-	}
-
-	// Style the tool name with color
-	nameColor := theme.Info
-	if isError {
-		nameColor = theme.Error
-	}
-	styledName := lipgloss.NewStyle().Foreground(nameColor).Bold(true).Render(displayName)
-	styledIcon := lipgloss.NewStyle().Foreground(iconColor).Render(icon)
-
-	// Build the content: icon + name + params on first line, then body
-	headerLine := styledIcon + " " + styledName
-	if params != "" {
-		headerLine += " " + lipgloss.NewStyle().Foreground(theme.Muted).Render(params)
-	}
-
-	if strings.TrimSpace(body) == "" {
-		body = ty.Italic("(no output)")
-	}
-
-	// Compose: icon + name + params, then body
-	fullContent := ty.Compose(
-		headerLine,
-		"",
-		body,
-	)
-	return styleMarginBottom(theme, fullContent)
-}
-
 // styleMarginBottom applies a 1-line margin bottom using the theme.
 func styleMarginBottom(theme style.Theme, content string) string {
 	return style.GetCachedStyles().MarginBottom1.Render(content)

internal/ui/render/blocks_test.go

@@ -4,30 +4,9 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/indaco/herald"
-
 	"github.com/mark3labs/kit/internal/ui/style"
 )
 
-// testTypography creates a herald Typography for tests.
-func testTypography(theme style.Theme) *herald.Typography {
-	return herald.New(
-		herald.WithPalette(herald.ColorPalette{
-			Primary:   theme.Primary,
-			Secondary: theme.Secondary,
-			Tertiary:  theme.Info,
-			Accent:    theme.Accent,
-			Highlight: theme.Highlight,
-			Muted:     theme.Muted,
-			Text:      theme.Text,
-			Surface:   theme.Background,
-			Base:      theme.CodeBg,
-		}),
-		herald.WithAlertLabel(herald.AlertTip, ""),
-		herald.WithAlertIcon(herald.AlertTip, ""),
-	)
-}
-
 func TestHighlightFileTokens(t *testing.T) {
 	theme := style.DefaultTheme()
 
@@ -88,24 +67,25 @@ func TestHighlightFileTokens(t *testing.T) {
 	}
 }
 
-func TestUserBlockHighlightsFileTokens(t *testing.T) {
+// TestHighlightFileTokensInjectsANSI verifies that HighlightFileTokens
+// preserves the original @file references in the output and wraps each
+// token with ANSI escape codes for the theme accent color.
+func TestHighlightFileTokensInjectsANSI(t *testing.T) {
 	theme := style.DefaultTheme()
-	ty := testTypography(theme)
 
-	// A user message with @file tokens should contain ANSI escapes around the token.
 	content := "refactor @main.go and @utils.go"
-	result := UserBlock(content, 80, ty, theme)
+	result := HighlightFileTokens(content, theme)
 
-	// The rendered output should contain both file references.
+	// The output should still contain both file references.
 	if !strings.Contains(result, "@main.go") {
-		t.Errorf("UserBlock output should contain @main.go, got:\n%s", result)
+		t.Errorf("HighlightFileTokens output should contain @main.go, got:\n%s", result)
 	}
 	if !strings.Contains(result, "@utils.go") {
-		t.Errorf("UserBlock output should contain @utils.go, got:\n%s", result)
+		t.Errorf("HighlightFileTokens output should contain @utils.go, got:\n%s", result)
 	}
 
 	// Verify ANSI codes are present (the tokens are styled).
 	if !strings.Contains(result, "\x1b[") {
-		t.Errorf("UserBlock output should contain ANSI escape codes for styled @file tokens")
+		t.Errorf("HighlightFileTokens output should contain ANSI escape codes for styled @file tokens")
 	}
 }

internal/ui/style/enhanced.go

@@ -211,106 +211,11 @@ func DefaultTheme() Theme {
 	}
 }
 
-// StyleCard creates a lipgloss style for card-like containers with rounded borders,
-// padding, and appropriate width. Used for grouping related content in a visually
-// distinct box.
-func StyleCard(width int, theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Width(width).
-		Border(lipgloss.RoundedBorder()).
-		BorderForeground(theme.Border).
-		Padding(1, 2).
-		MarginBottom(1)
-}
-
 // IsDarkBackground returns the cached terminal background detection result.
 func IsDarkBackground() bool {
 	return isDarkBg
 }
 
-// StyleHeader creates a lipgloss style for primary headers using the theme's
-// primary color with bold text for emphasis and hierarchy.
-func StyleHeader(theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Foreground(theme.Primary).
-		Bold(true)
-}
-
-// StyleSubheader creates a lipgloss style for secondary headers using the theme's
-// secondary color with bold text, providing visual hierarchy below primary headers.
-func StyleSubheader(theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Foreground(theme.Secondary).
-		Bold(true)
-}
-
-// StyleMuted creates a lipgloss style for de-emphasized text using muted colors
-// and italic formatting, suitable for supplementary or less important information.
-func StyleMuted(theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Foreground(theme.Muted).
-		Italic(true)
-}
-
-// StyleSuccess creates a lipgloss style for success messages using green colors
-// with bold text to indicate successful operations or positive outcomes.
-func StyleSuccess(theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Foreground(theme.Success).
-		Bold(true)
-}
-
-// StyleError creates a lipgloss style for error messages using red colors
-// with bold text to ensure visibility of problems or failures.
-func StyleError(theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Foreground(theme.Error).
-		Bold(true)
-}
-
-// StyleWarning creates a lipgloss style for warning messages using yellow/amber
-// colors with bold text to draw attention to potential issues or cautions.
-func StyleWarning(theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Foreground(theme.Warning).
-		Bold(true)
-}
-
-// StyleInfo creates a lipgloss style for informational messages using blue colors
-// with bold text for general notifications and status updates.
-func StyleInfo(theme Theme) lipgloss.Style {
-	return lipgloss.NewStyle().
-		Foreground(theme.Info).
-		Bold(true)
-}
-
-// CreateSeparator generates a horizontal separator line with the specified width,
-// character, and color. Useful for visually dividing sections of content in the UI.
-func CreateSeparator(width int, char string, c color.Color) string {
-	return lipgloss.NewStyle().
-		Foreground(c).
-		Width(width).
-		Render(lipgloss.PlaceHorizontal(width, lipgloss.Center, char))
-}
-
-// CreateProgressBar generates a visual progress bar with filled and empty segments
-// based on the percentage complete. The bar uses Unicode block characters for smooth
-// appearance and theme colors to indicate progress.
-func CreateProgressBar(width int, percentage float64, theme Theme) string {
-	filled := int(float64(width) * percentage / 100)
-	empty := width - filled
-
-	filledBar := lipgloss.NewStyle().
-		Foreground(theme.Success).
-		Render(lipgloss.PlaceHorizontal(filled, lipgloss.Left, "█"))
-
-	emptyBar := lipgloss.NewStyle().
-		Foreground(theme.Muted).
-		Render(lipgloss.PlaceHorizontal(empty, lipgloss.Left, "░"))
-
-	return filledBar + emptyBar
-}
-
 // CreateBadge generates a styled badge or label with inverted colors (text on
 // colored background) for highlighting important tags, statuses, or categories.
 func CreateBadge(text string, c color.Color) string {

internal/ui/style/styles.go

@@ -6,13 +6,6 @@ import (
 	heraldmd "github.com/indaco/herald-md"
 )
 
-// BaseStyle returns a new, empty lipgloss style that can be customized with
-// additional styling methods. This serves as the foundation for building more
-// complex styled components.
-func BaseStyle() lipgloss.Style {
-	return lipgloss.NewStyle()
-}
-
 // markdownTypographyCache holds the last-created Typography instance for
 // herald-md rendering. It is cached to avoid re-initialization on every
 // streaming flush tick. The cache is invalidated by SetTheme when the

internal/ui/style/themes.go

@@ -543,12 +543,6 @@ func ApplyThemeWithoutSave(name string) error {
 	return nil
 }
 
-// RefreshThemeRegistry re-scans the themes directory. Call after the user
-// drops a new file into ~/.config/kit/themes/.
-func RefreshThemeRegistry() {
-	initThemeRegistry()
-}
-
 // RegisterThemeFromConfig adds a theme to the runtime registry from an
 // extension's ThemeColorConfig (string hex pairs). Replaces any existing
 // entry with the same name. The theme is immediately available via

internal/ui/tool_approval_input.go

@@ -1,140 +0,0 @@
-package ui
-
-import (
-	"fmt"
-	"strings"
-
-	"charm.land/bubbles/v2/textarea"
-	tea "charm.land/bubbletea/v2"
-	"charm.land/lipgloss/v2"
-)
-
-type ToolApprovalInput struct {
-	textarea textarea.Model
-	toolName string
-	toolArgs string
-	width    int
-	selected bool // true when "yes" is highlighted and false when "no" is
-	approved bool
-	done     bool
-}
-
-func NewToolApprovalInput(toolName, toolArgs string, width int) *ToolApprovalInput {
-	ta := textarea.New()
-	ta.Placeholder = ""
-	ta.ShowLineNumbers = false
-	ta.CharLimit = 0
-	ta.SetWidth(width - 8) // Account for container padding, border and internal padding
-	ta.SetHeight(4)        // Default to 3 lines like huh
-	ta.Focus()
-
-	// Style the textarea using theme colors.
-	theme := GetTheme()
-	styles := ta.Styles()
-	styles.Focused.Base = lipgloss.NewStyle()
-	styles.Focused.Placeholder = lipgloss.NewStyle().Foreground(theme.VeryMuted)
-	styles.Focused.Text = lipgloss.NewStyle().Foreground(theme.Text)
-	styles.Focused.Prompt = lipgloss.NewStyle()
-	styles.Focused.CursorLine = lipgloss.NewStyle()
-	ta.SetStyles(styles)
-
-	return &ToolApprovalInput{
-		textarea: ta,
-		toolName: toolName,
-		toolArgs: toolArgs,
-		width:    width,
-		selected: true,
-	}
-}
-
-func (t *ToolApprovalInput) Init() tea.Cmd {
-	return textarea.Blink
-}
-
-func (t *ToolApprovalInput) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
-	switch msg := msg.(type) {
-	case tea.KeyPressMsg:
-		switch msg.String() {
-		case "y", "Y":
-			t.approved = true
-			t.done = true
-			return t, tea.Quit
-		case "n", "N":
-			t.approved = false
-			t.done = true
-			return t, tea.Quit
-		case "left":
-			t.selected = true
-			return t, nil
-		case "right":
-			t.selected = false
-			return t, nil
-		case "enter":
-			t.approved = t.selected
-			t.done = true
-			return t, tea.Quit
-		case "esc", "ctrl+c":
-			t.approved = false
-			t.done = true
-			return t, tea.Quit
-		}
-	}
-	return t, nil
-}
-
-func (t *ToolApprovalInput) View() tea.View {
-	if t.done {
-		return tea.NewView("we are done")
-	}
-
-	containerStyle := lipgloss.NewStyle()
-
-	theme := GetTheme()
-
-	// PaddingLeft(3) aligns with message content: border(1) + paddingLeft(2).
-	titleStyle := lipgloss.NewStyle().
-		Foreground(theme.Text).
-		MarginBottom(1).
-		PaddingLeft(3)
-
-	// Input box with huh-like styling
-	inputBoxStyle := lipgloss.NewStyle().
-		Border(lipgloss.ThickBorder()).
-		BorderLeft(true).
-		BorderRight(false).
-		BorderTop(false).
-		BorderBottom(false).
-		BorderForeground(theme.Primary).
-		PaddingLeft(2).    // match message block paddingLeft
-		Width(t.width - 1) // full width minus left border
-
-	// Style for the currently selected/highlighted option
-	selectedStyle := lipgloss.NewStyle().
-		Foreground(theme.Success).
-		Bold(true).
-		Underline(true)
-
-	// Style for the unselected/unhighlighted option
-	unselectedStyle := lipgloss.NewStyle().
-		Foreground(theme.VeryMuted)
-
-	// Build the view
-	var view strings.Builder
-	view.WriteString(titleStyle.Render("Allow tool execution"))
-	view.WriteString("\n")
-	details := fmt.Sprintf("Tool: %s\nArguments: %s\n\n", t.toolName, t.toolArgs)
-	view.WriteString(details)
-	view.WriteString("Allow tool execution: ")
-
-	var yesText, noText string
-	if t.selected {
-		yesText = selectedStyle.Render("[y]es")
-		noText = unselectedStyle.Render("[n]o")
-	} else {
-		yesText = unselectedStyle.Render("[y]es")
-		noText = selectedStyle.Render("[n]o")
-	}
-	view.WriteString(yesText + "/" + noText + "\n")
-
-	return tea.NewView(containerStyle.Render(inputBoxStyle.Render(view.String())))
-}

pkg/kit/events.go

@@ -148,9 +148,9 @@ func parseToolArgs(toolArgs string) map[string]any {
 // ---------------------------------------------------------------------------
 
 // Finish reasons reported by the LLM provider on a completed turn. These
-// mirror fantasy.FinishReason string values so comparisons against
-// TurnEndEvent.StopReason / TurnResult.StopReason are stable across
-// providers.
+// mirror the underlying provider's finish reason string values so
+// comparisons against TurnEndEvent.StopReason / TurnResult.StopReason are
+// stable across providers.
 const (
 	// FinishReasonStop: the model produced a natural stop (e.g. stop sequence
 	// or end-of-turn signal).

pkg/kit/kit.go

@@ -58,6 +58,9 @@ type Kit struct {
 	// When false, per-model system prompts from modelSettings/customModels
 	// can replace the default prompt on model switch.
 	hasCustomSystemPrompt bool
+	// systemPromptSource holds the raw configured value (file path or text)
+	// when hasCustomSystemPrompt is true; empty when the built-in default is in use.
+	systemPromptSource string
 
 	// Hook registries — interception layer (see hooks.go).
 	beforeToolCall  *hookRegistry[BeforeToolCallHook, BeforeToolCallResult]
@@ -632,6 +635,21 @@ func (m *Kit) SetModel(ctx context.Context, modelString string) error {
 	return nil
 }
 
+// HasCustomSystemPrompt reports whether the user explicitly configured a system
+// prompt via --system-prompt, a config file entry, or SDK Options.SystemPrompt.
+// When false, the built-in default (or a per-model override) is in use and can
+// be replaced transparently on model switch.
+func (m *Kit) HasCustomSystemPrompt() bool {
+	return m.hasCustomSystemPrompt
+}
+
+// GetSystemPromptSource returns the raw configured value — a file path or
+// inline text — when HasCustomSystemPrompt is true; returns an empty string
+// when the built-in default prompt is active.
+func (m *Kit) GetSystemPromptSource() string {
+	return m.systemPromptSource
+}
+
 // composeSystemPrompt takes a base system prompt and composes it with the
 // current runtime context: AGENTS.md content, skills metadata, and date/cwd.
 // This mirrors the composition done during Kit.New() initialization.
@@ -1179,6 +1197,7 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 		maxSteps              int
 		streaming             bool
 		hasCustomSystemPrompt bool
+		systemPromptSource    string
 	)
 
 	if err := func() error {
@@ -1285,13 +1304,27 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 		// explicitly set system-prompt, use the per-model prompt as the
 		// base instead of the global default.
 		{
-			basePrompt := viper.GetString("system-prompt")
+			rawPromptInput := viper.GetString("system-prompt")
+
+			// Resolve a file path to its content so PromptBuilder receives the
+			// actual prompt text rather than a literal path string. Without this,
+			// when system-prompt is set to a file path in the config file or via
+			// --system-prompt, the path itself becomes the effective system prompt
+			// sent to the model (LoadSystemPrompt only ran later, after viper had
+			// been overwritten with the augmented base text).
+			basePrompt, _ := config.LoadSystemPrompt(rawPromptInput)
+			if basePrompt == "" {
+				basePrompt = rawPromptInput
+			}
 
 			// Track whether the user explicitly configured a custom system
 			// prompt. When they haven't (basePrompt is the built-in default
 			// or empty), per-model system prompts can replace it on switch.
 			userSetSystemPrompt := basePrompt != "" && basePrompt != defaultSystemPrompt
 			hasCustomSystemPrompt = userSetSystemPrompt
+			if hasCustomSystemPrompt {
+				systemPromptSource = rawPromptInput
+			}
 
 			// Check for per-model system prompt override when no explicit
 			// global system-prompt was configured by the user.
@@ -1500,6 +1533,7 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 		opts:                  opts,
 		mcpConfig:             mcpConfig,
 		hasCustomSystemPrompt: hasCustomSystemPrompt,
+		systemPromptSource:    systemPromptSource,
 		beforeToolCall:        beforeToolCall,
 		afterToolResult:       afterToolResult,
 		beforeTurn:            beforeTurn,

pkg/kit/kit_test.go

@@ -3,6 +3,7 @@ package kit_test
 import (
 	"context"
 	"os"
+	"strings"
 	"testing"
 
 	"github.com/spf13/viper"
@@ -306,3 +307,92 @@ func TestSessionManagement(t *testing.T) {
 // resetViper wipes viper's global state so a test case doesn't leak
 // viper.Set() calls into the next one. Used via defer in subtests.
 func resetViper() { viper.Reset() }
+
+// TestNewSystemPromptFilePath is a regression test for issue #25.
+//
+// When Options.SystemPrompt (or the --system-prompt flag / config entry) is a
+// file path, Kit must resolve the path to its file contents *before* the
+// PromptBuilder composes the runtime context. Previously the path string
+// itself was used verbatim as the base prompt, so the LLM received the path —
+// not the prompt — as its system message.
+func TestNewSystemPromptFilePath(t *testing.T) {
+	if os.Getenv("ANTHROPIC_API_KEY") == "" {
+		t.Skip("Skipping test: ANTHROPIC_API_KEY not set")
+	}
+	defer resetViper()
+
+	const promptContent = "You are a strict regression-test persona. Marker: KIT-25-OK"
+
+	tmpFile, err := os.CreateTemp(t.TempDir(), "kit-system-prompt-*.md")
+	if err != nil {
+		t.Fatalf("failed to create temp prompt file: %v", err)
+	}
+	if _, err := tmpFile.WriteString(promptContent); err != nil {
+		t.Fatalf("failed to write temp prompt file: %v", err)
+	}
+	if err := tmpFile.Close(); err != nil {
+		t.Fatalf("failed to close temp prompt file: %v", err)
+	}
+
+	ctx := context.Background()
+	host, err := kit.New(ctx, &kit.Options{
+		Model:        "anthropic/claude-sonnet-4-5-20250929",
+		SystemPrompt: tmpFile.Name(),
+		Quiet:        true,
+		NoSession:    true,
+	})
+	if err != nil {
+		t.Fatalf("Failed to create Kit with system-prompt file: %v", err)
+	}
+	defer func() { _ = host.Close() }()
+
+	if !host.HasCustomSystemPrompt() {
+		t.Error("HasCustomSystemPrompt() = false; want true when --system-prompt is set")
+	}
+	if got, want := host.GetSystemPromptSource(), tmpFile.Name(); got != want {
+		t.Errorf("GetSystemPromptSource() = %q; want %q", got, want)
+	}
+
+	// The composed system prompt is written back to viper after PromptBuilder
+	// runs. It must contain the file's contents, not the file path.
+	composed := viper.GetString("system-prompt")
+	if !strings.Contains(composed, promptContent) {
+		t.Errorf("composed system-prompt does not contain file contents\n  composed = %q\n  want substring = %q", composed, promptContent)
+	}
+	if strings.TrimSpace(composed) == tmpFile.Name() {
+		t.Errorf("composed system-prompt is the file path verbatim (%q); LoadSystemPrompt was not applied before PromptBuilder", composed)
+	}
+}
+
+// TestNewSystemPromptInline confirms that inline system-prompt strings still
+// flow through unchanged after the file-path resolution change.
+func TestNewSystemPromptInline(t *testing.T) {
+	if os.Getenv("ANTHROPIC_API_KEY") == "" {
+		t.Skip("Skipping test: ANTHROPIC_API_KEY not set")
+	}
+	defer resetViper()
+
+	const inline = "You are a concise inline-prompt persona."
+
+	ctx := context.Background()
+	host, err := kit.New(ctx, &kit.Options{
+		Model:        "anthropic/claude-sonnet-4-5-20250929",
+		SystemPrompt: inline,
+		Quiet:        true,
+		NoSession:    true,
+	})
+	if err != nil {
+		t.Fatalf("Failed to create Kit with inline system-prompt: %v", err)
+	}
+	defer func() { _ = host.Close() }()
+
+	if !host.HasCustomSystemPrompt() {
+		t.Error("HasCustomSystemPrompt() = false; want true for inline prompt")
+	}
+	if got := host.GetSystemPromptSource(); got != inline {
+		t.Errorf("GetSystemPromptSource() = %q; want %q", got, inline)
+	}
+	if composed := viper.GetString("system-prompt"); !strings.Contains(composed, inline) {
+		t.Errorf("composed system-prompt missing inline content; got %q", composed)
+	}
+}

specs/README.md

@@ -1,5 +0,0 @@
-# Specs
-
-| Spec | Status | Description |
-|------|--------|-------------|
-| [unified-bubbletea-architecture](unified-bubbletea-architecture.md) | Draft | Replace micro-program pattern with single Bubble Tea program + thick app layer |