fix(models): route auto-discovered providers by wire protocol (#41)

- replace npmToLLMProvider map with npmToWireProtocol (openai/anthropic/google)
- add createAutoRoutedGoogleProvider so @ai-sdk/google proxies work
  (fixes opencode/gemini-* failing with "no LLM provider mapping")
- strip the genai-injected v1beta segment for proxies whose base URL
  already carries a version (e.g. opencode's /zen/v1)
- preserve openai-compat fallback and clearer error for unroutable providers
- document auto-routing in README and providers docs; update CreateProvider godoc
- add regression tests for wire routing and version-path rewriting

Fixes #41

README.md

@@ -127,6 +127,7 @@ max-tokens: 4096
 temperature: 0.7
 stream: true
 thinking-level: off       # off, none, minimal, low, medium, high
+no-core-tools: false      # set to true to disable all built-in core tools
 ```
 
 All of the above keys can also be set programmatically via the SDK
@@ -195,9 +196,10 @@ mcpServers:
 --compact                Enable compact output mode
 --auto-compact           Auto-compact conversation near context limit
 
-# Extensions
+# Extensions and tools
 --extension, -e          Load additional extension file(s) (repeatable)
 --no-extensions          Disable all extensions
+--no-core-tools          Disable all built-in core tools (bash, read, write, edit, grep, find, ls, subagent)
 --prompt-template        Load a specific prompt template by name
 --no-prompt-templates    Disable prompt template loading
 
@@ -554,7 +556,7 @@ host, err := kit.New(ctx, &kit.Options{
     SystemPrompt: "You are a helpful bot",
     ConfigFile:   "/path/to/config.yml",
     MaxSteps:     10,
-    Streaming:    true,
+    Streaming:    ptr(true), // *bool: nil = unset (default true), &false = off
     Quiet:        true,
 
     // Generation parameters (override env/config/per-model defaults)
@@ -579,7 +581,9 @@ host, err := kit.New(ctx, &kit.Options{
     // Tool options
     Tools:            []kit.Tool{...},     // Replace default tool set entirely
     ExtraTools:       []kit.Tool{...},     // Add tools alongside defaults
-    DisableCoreTools: true,                // Use no core tools (0 tools, for chat-only)
+    DisableCoreTools: true,                // Disable all built-in core tools; also controllable via
+                                           // --no-core-tools flag, KIT_NO_CORE_TOOLS env var,
+                                           // or no-core-tools: true in .kit.yml
 
     // Configuration
     SkipConfig:   true,                   // Skip .kit.yml files (viper defaults + env vars still apply)
@@ -599,6 +603,38 @@ are pointer types so explicit `0.0` is distinguishable from "leave alone"; a
 non-zero `MaxTokens` suppresses automatic right-sizing the same way `--max-tokens`
 does on the CLI.
 
+### Functional options (`NewAgent`)
+
+For simple programmatic setups, `kit.NewAgent` offers an ergonomic
+functional-options front door over `kit.New`. Streaming is **enabled by
+default**; pass `kit.WithStreaming(false)` to opt out.
+
+```go
+host, err := kit.NewAgent(ctx,
+    kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+    kit.WithSystemPrompt("You are a helpful assistant."),
+    kit.WithMaxTokens(8192),
+    kit.WithThinkingLevel("medium"),
+    kit.Ephemeral(), // in-memory session, no persistence
+)
+```
+
+Available options: `WithModel`, `WithSystemPrompt`, `WithStreaming`,
+`WithMaxTokens`, `WithThinkingLevel`, `WithTools`, `WithExtraTools`,
+`WithProviderAPIKey`, `WithProviderURL`, `WithConfigFile`, `WithDebug`, and
+`Ephemeral`. For advanced configuration not covered by the helpers (custom MCP
+config, in-process MCP servers, session backends, MCP task tuning) construct an
+`Options` value explicitly and call `kit.New`.
+
+### Per-instance config isolation
+
+Each `kit.New` / `kit.NewAgent` call owns an **isolated configuration store**,
+so constructing multiple Kit instances in the same process is safe: setting the
+model, thinking level, or generation parameters on one never affects another,
+and runtime mutators (`SetModel`, `SetThinkingLevel`) only touch the owning
+instance. This makes subagent spawning and multi-Kit embedding race-free with
+no external synchronization required.
+
 ### MCP OAuth (remote MCP servers)
 
 When a remote MCP server returns 401, Kit runs the full OAuth flow (dynamic
@@ -756,6 +792,45 @@ host, _ := kit.New(ctx, &kit.Options{
 })
 ```
 
+### Runtime Skills & Context Files
+
+For multi-tenant hosts (chatbots, per-user agents, web services), the SDK
+lets you swap skills and `AGENTS.md`-style context files **after** Kit
+construction. Every mutation recomposes the system prompt and applies it to
+the agent so the next turn picks up the new instructions — no restart needed.
+
+```go
+// Programmatic skill (no file on disk required).
+host.AddSkill(&kit.Skill{
+    Name:        "polite-french",
+    Description: "Respond in French and always greet the user.",
+    Content:     "Always reply in French. Open every response with 'Bonjour'.",
+})
+
+// Or load one from disk.
+host.LoadAndAddSkill("/var/skills/refund-policy.md")
+
+// Per-user AGENTS.md content pulled from a database.
+host.AddContextFileContent(
+    fmt.Sprintf("session://%s/AGENTS.md", userID),
+    rulesFromDB,
+)
+
+// Tear down session-specific state on logout.
+host.RemoveSkill("polite-french")
+host.RemoveContextFile(fmt.Sprintf("session://%s/AGENTS.md", userID))
+
+// Or replace the whole set atomically.
+host.SetSkills(activeSkillsForUser)
+host.SetContextFiles(activeContextForUser)
+```
+
+Skills dedupe by `Name`, context files dedupe by `Path` (which can be any
+opaque identifier — it doesn't have to be a real filesystem path). All
+mutators and readers (`GetSkills`, `GetContextFiles`) are safe to call
+concurrently from multiple goroutines. See the [SDK overview docs](/sdk/overview#runtime-skills-and-context-files)
+for the full reference.
+
 ## Advanced Usage
 
 ### Subagent Pattern
@@ -897,6 +972,31 @@ This automatically defaults to `custom/custom` without needing to specify a mode
 - Reasoning and temperature support
 - Optional `CUSTOM_API_KEY` environment variable or `--provider-api-key` flag
 
+### Auto-routed Providers
+
+Any provider in the [models.dev](https://models.dev) database can be used as
+`provider/model` without a dedicated native integration. Kit auto-routes the
+request through the matching **wire protocol** based on the provider's npm package
+(or per-model override), using its `api` URL as the base:
+
+| npm package | Wire protocol |
+|-------------|---------------|
+| `@ai-sdk/openai` | OpenAI (Responses API) |
+| `@ai-sdk/openai-compatible` | OpenAI (chat completions) |
+| `@ai-sdk/anthropic` | Anthropic |
+| `@ai-sdk/google` | Google Gemini |
+
+Providers with an `api` URL but an unrecognized npm package fall back to the
+OpenAI-compatible wire. Because routing follows the wire protocol, aggregator/proxy
+providers work across all of their models — including Claude, GPT, *and* Gemini
+routes:
+
+```bash
+kit --model opencode/claude-haiku-4-5 "Hello"     # → Anthropic wire
+kit --model opencode/gpt-5 "Hello"                # → OpenAI wire
+kit --model opencode/gemini-3.5-flash "Hello"     # → Google wire
+```
+
 ### Model String Format
 
 ```bash

cmd/root.go

@@ -71,6 +71,7 @@ var (
 
 	// Extensions control
 	noExtensionsFlag bool
+	noCoreToolsFlag  bool
 	extensionPaths   []string
 
 	// TLS configuration
@@ -278,6 +279,8 @@ func init() {
 		BoolVar(&noSessionFlag, "no-session", false, "ephemeral mode — no session persistence")
 	rootCmd.PersistentFlags().
 		BoolVar(&noExtensionsFlag, "no-extensions", false, "disable all extensions")
+	rootCmd.PersistentFlags().
+		BoolVar(&noCoreToolsFlag, "no-core-tools", false, "disable all built-in core tools (bash, read, write, edit, grep, find, ls, subagent)")
 	rootCmd.PersistentFlags().
 		StringSliceVarP(&extensionPaths, "extension", "e", nil, "load additional extension file(s)")
 
@@ -327,6 +330,7 @@ func init() {
 	_ = viper.BindPFlag("main-gpu", rootCmd.PersistentFlags().Lookup("main-gpu"))
 	_ = viper.BindPFlag("tls-skip-verify", rootCmd.PersistentFlags().Lookup("tls-skip-verify"))
 	_ = viper.BindPFlag("no-extensions", rootCmd.PersistentFlags().Lookup("no-extensions"))
+	_ = viper.BindPFlag("no-core-tools", rootCmd.PersistentFlags().Lookup("no-core-tools"))
 	_ = viper.BindPFlag("extension", rootCmd.PersistentFlags().Lookup("extension"))
 	_ = viper.BindPFlag("prompt-template", rootCmd.PersistentFlags().Lookup("prompt-template"))
 	_ = viper.BindPFlag("no-prompt-templates", rootCmd.PersistentFlags().Lookup("no-prompt-templates"))
@@ -772,13 +776,14 @@ func runNormalMode(ctx context.Context) error {
 	var appInstancePtr *app.App
 
 	kitOpts := &kit.Options{
-		Quiet:          quietFlag,
-		Debug:          debugMode,
-		NoSession:      noSessionFlag,
-		Continue:       continueFlag,
-		SessionPath:    sessionPath,
-		AutoCompact:    autoCompactFlag,
-		MCPAuthHandler: authHandler,
+		Quiet:            quietFlag,
+		Debug:            debugMode,
+		NoSession:        noSessionFlag,
+		Continue:         continueFlag,
+		SessionPath:      sessionPath,
+		AutoCompact:      autoCompactFlag,
+		MCPAuthHandler:   authHandler,
+		DisableCoreTools: viper.GetBool("no-core-tools"),
 		// This callback is called when each MCP server finishes loading.
 		// We use a closure that captures appInstancePtr which is set after
 		// app.New() is called below.
@@ -899,8 +904,9 @@ func runNormalMode(ctx context.Context) error {
 			appInstance:  appInstance,
 			usageTracker: usageTracker,
 		})
+
+		// During startup, buffer extension messages so they appear after the banner.
 		extCtx.Print = func(text string) {
-			// Capture messages during startup, print after startup banner.
 			startupExtensionMessages = append(startupExtensionMessages, text)
 		}
 		extCtx.PrintInfo = func(text string) {
@@ -913,15 +919,6 @@ func runNormalMode(ctx context.Context) error {
 		kitInstance.Extensions().EmitSessionStart()
 
 		// Restore normal print functions for runtime use.
-		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) }

examples/sdk/README.md

@@ -42,4 +42,14 @@ defer host.Close()
 response, err := host.Prompt(ctx, "Hello!")
 ```
 
+Or use the functional-options constructor for quick setups (streaming defaults on):
+
+```go
+host, err := kit.NewAgent(ctx,
+    kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+    kit.WithSystemPrompt("You are a helpful assistant."),
+    kit.Ephemeral(),
+)
+```
+
 See the [SDK README](../../pkg/kit/README.md) for the full API reference.

go.mod

@@ -1,32 +1,32 @@
 module github.com/mark3labs/kit
 
-go 1.26.2
+go 1.26.3
 
 require (
 	charm.land/bubbles/v2 v2.1.0
 	charm.land/bubbletea/v2 v2.0.6
-	charm.land/fantasy v0.23.0
+	charm.land/fantasy v0.25.0
 	charm.land/huh/v2 v2.0.3
 	charm.land/lipgloss/v2 v2.0.3
-	github.com/alecthomas/chroma/v2 v2.24.1
+	github.com/alecthomas/chroma/v2 v2.26.1
 	github.com/atotto/clipboard v0.1.4
 	github.com/aymanbagabas/go-udiff v0.4.1
 	github.com/charmbracelet/fang v1.0.0
 	github.com/charmbracelet/log v1.0.0
 	github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266
-	github.com/charmbracelet/ultraviolet v0.0.0-20260428153724-66037269d7be
+	github.com/charmbracelet/ultraviolet v0.0.0-20260525132238-948f4557a654
 	github.com/charmbracelet/x/editor v0.2.0
 	github.com/clipperhouse/displaywidth v0.11.0
 	github.com/clipperhouse/uax29/v2 v2.7.0
-	github.com/coder/acp-go-sdk v0.12.2
+	github.com/coder/acp-go-sdk v0.13.0
 	github.com/fsnotify/fsnotify v1.10.1
 	github.com/indaco/herald v0.13.0
 	github.com/indaco/herald-md v0.3.0
-	github.com/mark3labs/mcp-go v0.51.0
+	github.com/mark3labs/mcp-go v0.54.1
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/traefik/yaegi v0.16.1
-	golang.org/x/term v0.42.0
+	golang.org/x/term v0.43.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -37,21 +37,21 @@ require (
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.1 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0 // indirect
-	github.com/aws/aws-sdk-go-v2 v1.41.7 // indirect
+	github.com/aws/aws-sdk-go-v2 v1.41.8 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 // indirect
-	github.com/aws/aws-sdk-go-v2/config v1.32.17 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.16 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24 // indirect
+	github.com/aws/aws-sdk-go-v2/config v1.32.19 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.18 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.24 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.24 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.24 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.25 // indirect
 	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.0.11 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 // indirect
-	github.com/aws/smithy-go v1.25.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.24 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.1.0 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.18 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.42.2 // indirect
+	github.com/aws/smithy-go v1.26.0 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/charmbracelet/anthropic-sdk-go v0.0.0-20260223140439-63879b0b8dab // indirect
@@ -59,17 +59,18 @@ require (
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
-	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260503005035-c113ba3d2310 // indirect
+	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260527151214-009e6338d40d // indirect
 	github.com/charmbracelet/x/exp/ordered v0.1.0 // indirect
-	github.com/charmbracelet/x/exp/slice v0.0.0-20260503005035-c113ba3d2310 // indirect
+	github.com/charmbracelet/x/exp/slice v0.0.0-20260527151214-009e6338d40d // indirect
 	github.com/charmbracelet/x/exp/strings v0.1.0 // indirect
 	github.com/charmbracelet/x/json v0.2.0 // indirect
 	github.com/charmbracelet/x/termios v0.1.1 // indirect
 	github.com/charmbracelet/x/windows v0.2.2 // indirect
 	github.com/dlclark/regexp2 v1.12.0 // indirect
+	github.com/dlclark/regexp2/v2 v2.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
-	github.com/go-json-experiment/json v0.0.0-20260430182902-b6187a392ed4 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260520185125-572e7c383686 // indirect
 	github.com/go-logfmt/logfmt v0.6.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
@@ -79,13 +80,13 @@ require (
 	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/googleapis/enterprise-certificate-proxy v0.3.15 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.16 // indirect
 	github.com/googleapis/gax-go/v2 v2.22.0 // indirect
 	github.com/gorilla/websocket v1.5.3 // indirect
-	github.com/kaptinlin/go-i18n v0.4.7 // indirect
-	github.com/kaptinlin/jsonpointer v0.4.21 // indirect
+	github.com/kaptinlin/go-i18n v0.4.5 // indirect
+	github.com/kaptinlin/jsonpointer v0.4.25 // indirect
 	github.com/kaptinlin/jsonschema v0.7.13 // indirect
-	github.com/kaptinlin/messageformat-go v0.6.3 // indirect
+	github.com/kaptinlin/messageformat-go v0.6.0 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
 	github.com/muesli/mango v0.2.0 // indirect
 	github.com/muesli/mango-cobra v1.3.0 // indirect
@@ -97,7 +98,7 @@ require (
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
-	github.com/tidwall/gjson v1.18.0 // indirect
+	github.com/tidwall/gjson v1.19.0 // indirect
 	github.com/tidwall/match v1.2.0 // indirect
 	github.com/tidwall/pretty v1.2.1 // indirect
 	github.com/tidwall/sjson v1.2.5 // indirect
@@ -105,21 +106,21 @@ require (
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/yuin/goldmark v1.8.2 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.68.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0 // indirect
-	go.opentelemetry.io/otel v1.43.0 // indirect
-	go.opentelemetry.io/otel/metric v1.43.0 // indirect
-	go.opentelemetry.io/otel/trace v1.43.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.69.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
+	go.opentelemetry.io/otel v1.44.0 // indirect
+	go.opentelemetry.io/otel/metric v1.44.0 // indirect
+	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.50.0 // indirect
-	golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f // indirect
-	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/crypto v0.52.0 // indirect
+	golang.org/x/exp v0.0.0-20260528193900-50dc527dd6c7 // indirect
+	golang.org/x/net v0.55.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	google.golang.org/api v0.277.0 // indirect
-	google.golang.org/genai v1.55.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260427160629-7cedc36a6bc4 // indirect
-	google.golang.org/grpc v1.81.0 // indirect
+	google.golang.org/api v0.282.0 // indirect
+	google.golang.org/genai v1.58.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
+	google.golang.org/grpc v1.81.1 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )
@@ -137,6 +138,6 @@ require (
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.10
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
-	golang.org/x/text v0.36.0
+	golang.org/x/sys v0.45.0 // indirect
+	golang.org/x/text v0.37.0
 )

go.sum

@@ -2,8 +2,8 @@ charm.land/bubbles/v2 v2.1.0 h1:YSnNh5cPYlYjPxRrzs5VEn3vwhtEn3jVGRBT3M7/I0g=
 charm.land/bubbles/v2 v2.1.0/go.mod h1:l97h4hym2hvWBVfmJDtrEHHCtkIKeTEb3TTJ4ZOB3wY=
 charm.land/bubbletea/v2 v2.0.6 h1:UHN/91OyuhaOFGSrBXQ/hMZD8IO1Uc4BvHlgHXL2WJo=
 charm.land/bubbletea/v2 v2.0.6/go.mod h1:MH/D8ZLlN3op37vQvijKuU29g3rqTp+aQapURFonF9g=
-charm.land/fantasy v0.23.0 h1:pocjwC5CxfEg1Bpwb0raML2d5ijo3op33Mmd6hYJyo4=
-charm.land/fantasy v0.23.0/go.mod h1:4yzSsd9XmFEVjRnF1P0LTEbLTmQX6OLnPkrHaf7iruo=
+charm.land/fantasy v0.25.0 h1:oXOWY1ivmTSnhYGzAolscF8zKtavWZyBWv0LHRSwN5Q=
+charm.land/fantasy v0.25.0/go.mod h1:8QrWUzIcKwZQP+aAnC9vLu3iID6hu9/Jt+rPMiieBkc=
 charm.land/huh/v2 v2.0.3 h1:2cJsMqEPwSywGHvdlKsJyQKPtSJLVnFKyFbsYZTlLkU=
 charm.land/huh/v2 v2.0.3/go.mod h1:93eEveeeqn47MwiC3tf+2atZ2l7Is88rAtmZNZ8x9Wc=
 charm.land/lipgloss/v2 v2.0.3 h1:yM2zJ4Cf5Y51b7RHIwioil4ApI/aypFXXVHSwlM6RzU=
@@ -28,42 +28,42 @@ github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ
 github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
 github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
-github.com/alecthomas/chroma/v2 v2.24.1 h1:m5ffpfZbIb++k8AqFEKy9uVgY12xIQtBsQlc6DfZJQM=
-github.com/alecthomas/chroma/v2 v2.24.1/go.mod h1:l+ohZ9xRXIbGe7cIW+YZgOGbvuVLjMps/FYN/CwuabI=
+github.com/alecthomas/chroma/v2 v2.26.1 h1:2X21EdxGZNv5GF9mG5u+uzc02GCFyGxbcBm3Grd9A78=
+github.com/alecthomas/chroma/v2 v2.26.1/go.mod h1:lxhRRa9H4hPmRLOOdYga4zkQIQjq3dtrrdwQeCfu78Y=
 github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs=
 github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
 github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
-github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
-github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
+github.com/aws/aws-sdk-go-v2 v1.41.8 h1:sRs7nG6/RiEBZ/K5UO2sNw0w40U02Nmz1VtARloTZXk=
+github.com/aws/aws-sdk-go-v2 v1.41.8/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10/go.mod h1:qqY157uZoqm5OXq/amuaBJyC9hgBCBQnsaWnPe905GY=
-github.com/aws/aws-sdk-go-v2/config v1.32.17 h1:FpL4/758/diKwqbytU0prpuiu60fgXKUWCpDJtApclU=
-github.com/aws/aws-sdk-go-v2/config v1.32.17/go.mod h1:OXqUMzgXytfoF9JaKkhrOYsyh72t9G+MJH8mMRaexOE=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.16 h1:r3RJBuU7X9ibt8RHbMjWE6y60QbKBiII6wSrXnapxSU=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.16/go.mod h1:6cx7zqDENJDbBIIWX6P8s0h6hqHC8Avbjh9Dseo27ug=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23 h1:UuSfcORqNSz/ey3VPRS8TcVH2Ikf0/sC+Hdj400QI6U=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23/go.mod h1:+G/OSGiOFnSOkYloKj/9M35s74LgVAdJBSD5lsFfqKg=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23 h1:GpT/TrnBYuE5gan2cZbTtvP+JlHsutdmlV2YfEyNde0=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23/go.mod h1:xYWD6BS9ywC5bS3sz9Xh04whO/hzK2plt2Zkyrp4JuA=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23 h1:bpd8vxhlQi2r1hiueOw02f/duEPTMK59Q4QMAoTTtTo=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23/go.mod h1:15DfR2nw+CRHIk0tqNyifu3G1YdAOy68RftkhMDDwYk=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24 h1:OQqn11BtaYv1WLUowvcA30MpzIu8Ti4pcLPIIyoKZrA=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24/go.mod h1:X5ZJyfwVrWA96GzPmUCWFQaEARPR7gCrpq2E92PJwAE=
+github.com/aws/aws-sdk-go-v2/config v1.32.19 h1:qRhIJMbevHUvIE7X4TK8N8zye5+5AhapcslPrvB+qKE=
+github.com/aws/aws-sdk-go-v2/config v1.32.19/go.mod h1:RbJ24nfoya63+Mf5VI+CGCGk9vEdv28xPeii+gojRYs=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.18 h1:GcXQz2M/0ZvMo0v5DakUqbDBeBM1ZNaivkolEF4Esgw=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.18/go.mod h1:sHJ06tMGcD3ZpmMyJqV+VBsGilhSIZPIN+ZFy5Dg0C4=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.24 h1:FQm5ApnyzkuJdXLGskPce83CK1CQKC4RUnIHKVe4BU4=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.24/go.mod h1:JsC7dqQc55MlZ5mvNsDMMge71u8pVcSzU3RNz2h/5yQ=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.24 h1:u6kJU2i0va1AgtJsH3RdWKWqHULlTh7zHwb35Womf74=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.24/go.mod h1:7GY+xLcXOFUpCkNwDReft9qOAVg54A4/AnjHIU7sSAY=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.24 h1:Xhbcf3KugX6vX7SDyUK205Oicyfg7EGuvoVNyP5L6DM=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.24/go.mod h1:rwDgb2HNOGZsnTHylOUedM7Vnl+bCfnXDqUNPsFWYfk=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.25 h1:54CTMmlJ71Rk2dYvM9qZOob+39wjlVja2zDLxCu69Ew=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.25/go.mod h1:BZaHqxsS9vN1fvV5EfEl0OBLOk5+AajWsMu6MjqnZB4=
 github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9 h1:FLudkZLt5ci0ozzgkVo8BJGwvqNaZbTWb3UcucAateA=
 github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9/go.mod h1:w7wZ/s9qK7c8g4al+UyoF1Sp/Z45UwMGcqIzLWVQHWk=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23 h1:pbrxO/kuIwgEsOPLkaHu0O+m4fNgLU8B3vxQ+72jTPw=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23/go.mod h1:/CMNUqoj46HpS3MNRDEDIwcgEnrtZlKRaHNaHxIFpNA=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.11 h1:TdJ+HdzOBhU8+iVAOGUTU63VXopcumCOF1paFulHWZc=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.11/go.mod h1:R82ZRExE/nheo0N+T8zHPcLRTcH8MGsnR3BiVGX0TwI=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 h1:7byT8HUWrgoRp6sXjxtZwgOKfhss5fW6SkLBtqzgRoE=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.17/go.mod h1:xNWknVi4Ezm1vg1QsB/5EWpAJURq22uqd38U8qKvOJc=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 h1:+1Kl1zx6bWi4X7cKi3VYh29h8BvsCoHQEQ6ST9X8w7w=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21/go.mod h1:4vIRDq+CJB2xFAXZ+YgGUTiEft7oAQlhIs71xcSeuVg=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 h1:F/M5Y9I3nwr2IEpshZgh1GeHpOItExNM9L1euNuh/fk=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.1/go.mod h1:mTNxImtovCOEEuD65mKW7DCsL+2gjEH+RPEAexAzAio=
-github.com/aws/smithy-go v1.25.1 h1:J8ERsGSU7d+aCmdQur5Txg6bVoYelvQJgtZehD12GkI=
-github.com/aws/smithy-go v1.25.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.24 h1:CQW2FTrflfoslYWLf3fv7vG28Q219+v8YJS5QTQb2+Y=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.24/go.mod h1:Xfx13T+u3nH6EEzgl9fBSO6nDRmze1FvnZNYkctQ2zw=
+github.com/aws/aws-sdk-go-v2/service/signin v1.1.0 h1:yQo3eZ5qFaL1sJWqs1nL6j3yPHA2/R7c6tQ4T+0IO10=
+github.com/aws/aws-sdk-go-v2/service/signin v1.1.0/go.mod h1:3Zzou41Qt/ueXfIzHvTEjDNuR5IjCUBVF01SNhrt1e8=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.18 h1:ApLTFdAZfDhZSiY5uskwECKHkSNNF83y2Ru2r7SezWA=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.18/go.mod h1:A9K9qx2l6nK89hp+a350FdGfRkrkH5HdiEjHbiy/Q/c=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.1 h1:4VD7TIZOGzehrgQ8vDE+1c6BQW4ErZPGY8ohZT5LXEE=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.1/go.mod h1:er0SFJfdV89Rit5hIJu/EXtv+qC2XMnxoksLmcUFkqM=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.2 h1:XKnxlM4KZH1gktcsh3zSWc7GW4KivEv/OkifmHOhCUY=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.2/go.mod h1:KJYmkQaFB3SUW2j3aBkPsxNmAb4ZsSOvbvCpuxzHJA0=
+github.com/aws/smithy-go v1.26.0 h1:9ouqbi+NyKP7fV3Te7UElCwdAb6Y8uk7LGwPE5tVe/s=
+github.com/aws/smithy-go v1.26.0/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
 github.com/aymanbagabas/go-udiff v0.4.1 h1:OEIrQ8maEeDBXQDoGCbbTTXYJMYRCRO1fnodZ12Gv5o=
@@ -86,8 +86,8 @@ github.com/charmbracelet/log v1.0.0 h1:HVVVMmfOorfj3BA9i8X8UL69Hoz9lI0PYwXfJvOdR
 github.com/charmbracelet/log v1.0.0/go.mod h1:uYgY3SmLpwJWxmlrPwXvzVYujxis1vAKRV/0VQB7yWA=
 github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266 h1:BW/sZtyd1JyYy0h5adMm3tzpNyL857LWjuTRET6OhpY=
 github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266/go.mod h1:1DahUaExbUZx/jD+FNT2PKP4L9rLE5+ZBRuI8mZjd/E=
-github.com/charmbracelet/ultraviolet v0.0.0-20260428153724-66037269d7be h1:j7w8VP/D4lu5+/4GamMmFy8nrtadcl82/fjvDgSHwLo=
-github.com/charmbracelet/ultraviolet v0.0.0-20260428153724-66037269d7be/go.mod h1:3YdTxlnV/L0bQ3VN8WOSw8doF7LZV/xawUQ4MuAPDvo=
+github.com/charmbracelet/ultraviolet v0.0.0-20260525132238-948f4557a654 h1:FpSYhY28ucg9ZRr+2wj67FAQ0Ey5yiK0072PmRDJNek=
+github.com/charmbracelet/ultraviolet v0.0.0-20260525132238-948f4557a654/go.mod h1:hFpumms29Smx3LStRfku8vcCTBe1Kq8aCXtHUJa3mjY=
 github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
 github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
 github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
@@ -98,14 +98,14 @@ github.com/charmbracelet/x/editor v0.2.0 h1:7XLUKtaRaB8jN7bWU2p2UChiySyaAuIfYiIR
 github.com/charmbracelet/x/editor v0.2.0/go.mod h1:p3oQ28TSL3YPd+GKJ1fHWcp+7bVGpedHpXmo0D6t1dY=
 github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86 h1:JSt3B+U9iqk37QUU2Rvb6DSBYRLtWqFqfxf8l5hOZUA=
 github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86/go.mod h1:2P0UgXMEa6TsToMSuFqKFQR+fZTO9CNGUNokkPatT/0=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260503005035-c113ba3d2310 h1:rByFKh9JgQScu7oy0+TlUbC2e93woW/QNZmNXbbbw/E=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260503005035-c113ba3d2310/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260527151214-009e6338d40d h1:sMilwx1YIYTrQva6jsB522AoRYAerNaDIKP4ZPtUq0A=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260527151214-009e6338d40d/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f h1:pk6gmGpCE7F3FcjaOEKYriCvpmIN4+6OS/RD0vm4uIA=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f/go.mod h1:IfZAMTHB6XkZSeXUqriemErjAWCCzT0LwjKFYCZyw0I=
 github.com/charmbracelet/x/exp/ordered v0.1.0 h1:55/qLwjIh0gL0Vni+QAWk7T/qRVP6sBf+2agPBgnOFE=
 github.com/charmbracelet/x/exp/ordered v0.1.0/go.mod h1:5UHwmG+is5THxMyCJHNPCn2/ecI07aKNrW+LcResjJ8=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260503005035-c113ba3d2310 h1:PMjHdSo8Vpq9psUw9BoHo9JLPMkm9Hqb+Whk64n3AQQ=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260503005035-c113ba3d2310/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260527151214-009e6338d40d h1:RxcAR+vJCoD8QqT1cqLtkQKw+1cqvjqnu5IpPqYzPco=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260527151214-009e6338d40d/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
 github.com/charmbracelet/x/exp/strings v0.1.0 h1:i69S2XI7uG1u4NLGeJPSYU++Nmjvpo9nwd6aoEm7gkA=
 github.com/charmbracelet/x/exp/strings v0.1.0/go.mod h1:/ehtMPNh9K4odGFkqYJKpIYyePhdp1hLBRvyY4bWkH8=
 github.com/charmbracelet/x/json v0.2.0 h1:DqB+ZGx2h+Z+1s98HOuOyli+i97wsFQIxP2ZQANTPrQ=
@@ -124,8 +124,8 @@ github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJ
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os8IaYg++6uMOdKK83QtkkvJik=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=
-github.com/coder/acp-go-sdk v0.12.2 h1:fpRJ8Z5HMSr5cZ5IywzFlFZcIxZOsto+laNVu7XelFA=
-github.com/coder/acp-go-sdk v0.12.2/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
+github.com/coder/acp-go-sdk v0.13.0 h1:IAKBDIbe/iBfKAGikeIndzb8fowt4ioD+gCtSU4HwMA=
+github.com/coder/acp-go-sdk v0.13.0/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
 github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
@@ -133,6 +133,8 @@ github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dlclark/regexp2 v1.12.0 h1:0j4c5qQmnC6XOWNjP3PIXURXN2gWx76rd3KvgdPkCz8=
 github.com/dlclark/regexp2 v1.12.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dlclark/regexp2/v2 v2.1.1 h1:LCUGyd9Wf+r+VVOl8Ny38JTpWJcAsdVnCIuhhtthmKw=
+github.com/dlclark/regexp2/v2 v2.1.1/go.mod h1:avUrQvPaLz2DrFNHJF0taWAFFX2C1GMSSoeiqFjcBmU=
 github.com/dnaeon/go-vcr v1.2.0 h1:zHCHvJYTMh1N7xnV7zf1m1GPBF9Ad0Jk/whtQ1663qI=
 github.com/dnaeon/go-vcr v1.2.0/go.mod h1:R4UdLID7HZT3taECzJs4YgbbH6PIGXB6W/sc5OLb6RQ=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
@@ -148,8 +150,8 @@ github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHk
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
 github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
-github.com/go-json-experiment/json v0.0.0-20260430182902-b6187a392ed4 h1:2WmHkJINIjgXXYDGik8d3oJvFA3DAwPy00csDJ3vo+o=
-github.com/go-json-experiment/json v0.0.0-20260430182902-b6187a392ed4/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/go-json-experiment/json v0.0.0-20260520185125-572e7c383686 h1:NZBJxCpbHS1gzS6xAmyxbJznosZIIPk9IB42v62UvKA=
+github.com/go-json-experiment/json v0.0.0-20260520185125-572e7c383686/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
 github.com/go-logfmt/logfmt v0.6.1 h1:4hvbpePJKnIzH1B+8OR/JPbTx37NktoI9LE2QZBBkvE=
 github.com/go-logfmt/logfmt v0.6.1/go.mod h1:EV2pOAQoZaT1ZXZbqDl5hrymndi4SY9ED9/z6CO0XAk=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -173,8 +175,8 @@ github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
 github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-github.com/googleapis/enterprise-certificate-proxy v0.3.15 h1:xolVQTEXusUcAA5UgtyRLjelpFFHWlPQ4XfWGc7MBas=
-github.com/googleapis/enterprise-certificate-proxy v0.3.15/go.mod h1:vqVt9yG9480NtzREnTlmGSBmFrA+bzb0yl0TxoBQXOg=
+github.com/googleapis/enterprise-certificate-proxy v0.3.16 h1:F/VPrx0YPBdksZJQdCAp0WUsqnNmZpUZszzfYt0M5Dw=
+github.com/googleapis/enterprise-certificate-proxy v0.3.16/go.mod h1:9Yb0eAkH/Xqhvv3zbeKf/+wMJqCeocWc6KIhDvEAuYE=
 github.com/googleapis/gax-go/v2 v2.22.0 h1:PjIWBpgGIVKGoCXuiCoP64altEJCj3/Ei+kSU5vlZD4=
 github.com/googleapis/gax-go/v2 v2.22.0/go.mod h1:irWBbALSr0Sk3qlqb9SyJ1h68WjgeFuiOzI4Rqw5+aY=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
@@ -187,14 +189,14 @@ github.com/indaco/herald v0.13.0 h1:+xVG9Fx5NpuWhwku/9IlRL6I009NnX4VUGKvlZHTRxU=
 github.com/indaco/herald v0.13.0/go.mod h1:T5g1+XLYvpjouhzAGHnAHDCKizhESkoV6+QPZ3DhgWA=
 github.com/indaco/herald-md v0.3.0 h1:hN1cKyrexPPM9PeHBsKuaWvIizSi/iYvM9yzRgtdb8M=
 github.com/indaco/herald-md v0.3.0/go.mod h1:RUHVaDSG45ymJjKyxpDwBocLXrZo93FB4OeYMsw9B9s=
-github.com/kaptinlin/go-i18n v0.4.7 h1:apjIIZHnGRyrkiX3vHj07F1BF6D0JLmV+VGSr1781Jc=
-github.com/kaptinlin/go-i18n v0.4.7/go.mod h1:+i1J0pFq/9i9ESC5qRMVkKwC+mdQTABhhBExpYOlbeM=
-github.com/kaptinlin/jsonpointer v0.4.21 h1:WVkwQbeerbHFcoXG7Yo/mlQhhZjWiTnagECEfwDXXa0=
-github.com/kaptinlin/jsonpointer v0.4.21/go.mod h1:Mo7+DX8RlQTFqS4dnYJl0izSP4ob+Rl5xO/mGDETgaU=
+github.com/kaptinlin/go-i18n v0.4.5 h1:9tIlo5A0RXth+yZJO2MG7Bhpu/X9PlzQnGz/qyYWNoY=
+github.com/kaptinlin/go-i18n v0.4.5/go.mod h1:mU/7BH4molY5lGZYBwBRKAaiJ70dWRHuqmQ0/pFLGno=
+github.com/kaptinlin/jsonpointer v0.4.25 h1:iJ197e8n+WwqaqBsa53FqG3rPJCg5oijyFXEXNWWC3E=
+github.com/kaptinlin/jsonpointer v0.4.25/go.mod h1:wVOBaXGGnP42YsMb6zev/3W5POTvspdNfh8DXzf8XS8=
 github.com/kaptinlin/jsonschema v0.7.13 h1:kahVXTy/rURL0XJjyQ9WELm59wEmXi6IY0TWswQEFvU=
 github.com/kaptinlin/jsonschema v0.7.13/go.mod h1:Uh0aUBusnhXDCEXJ2oimL/hx7YTo7F+sKniE+tM0ERc=
-github.com/kaptinlin/messageformat-go v0.6.3 h1:m9ZE/fCjnsk8bdkv7Qs56L/ZoHbmQqhz9mRZSAQLU5g=
-github.com/kaptinlin/messageformat-go v0.6.3/go.mod h1:2KOZ/hgo/SveZ+uyi7vPUpUXieX65Mppzbc3VpGyqKs=
+github.com/kaptinlin/messageformat-go v0.6.0 h1:D6jiXFsKW4/JG2CMddv/F6Rev9KVbCRKEzzV5QOAcpc=
+github.com/kaptinlin/messageformat-go v0.6.0/go.mod h1:NKjwS6e9u7DRhAK+vydjDDwJ7UbdHhYjk/yk2WPuZPs=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -203,8 +205,8 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
 github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/mark3labs/mcp-go v0.51.0 h1:e8AhEfxzcYt7XqYzwT7uzWNhnqpu3H1Tn7dEJB9Ygj8=
-github.com/mark3labs/mcp-go v0.51.0/go.mod h1:Zg9cB2HdwdMMVgY0xtTzq3KvYIOJQDsaut+jWjwDaQY=
+github.com/mark3labs/mcp-go v0.54.1 h1:Ap/ptEB9FtWzFKM8NDsTA7QDxerQOC06eZigrTldVj0=
+github.com/mark3labs/mcp-go v0.54.1/go.mod h1:+8WclSK1ZUweCP3hvktSji8n8ABG/95QaEkeVE/Uwas=
 github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
 github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
 github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
@@ -256,8 +258,8 @@ github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/tidwall/gjson v1.14.2/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
-github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
-github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/gjson v1.19.0 h1:xwxm7n691Uf3u5OFjzngavjGTh55KX5q/9w9xHW88JU=
+github.com/tidwall/gjson v1.19.0/go.mod h1:V37/opeE/JbLUOfH0QTXiNez2l0RUjYUhpT4szFQAfc=
 github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
 github.com/tidwall/match v1.2.0 h1:0pt8FlkOwjN2fPt4bIl4BoNxb98gGHN2ObFEDkrfZnM=
 github.com/tidwall/match v1.2.0/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
@@ -276,54 +278,54 @@ github.com/yuin/goldmark v1.8.2 h1:kEGpgqJXdgbkhcOgBxkC0X0PmoPG1ZyoZ117rDVp4zE=
 github.com/yuin/goldmark v1.8.2/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.68.0 h1:0Qx7VGBacMm9ZENQ7TnNObTYI4ShC+lHI16seduaxZo=
-go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.68.0/go.mod h1:Sje3i3MjSPKTSPvVWCaL8ugBzJwik3u4smCjUeuupqg=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0 h1:CqXxU8VOmDefoh0+ztfGaymYbhdB/tT3zs79QaZTNGY=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0/go.mod h1:BuhAPThV8PBHBvg8ZzZ/Ok3idOdhWIodywz2xEcRbJo=
-go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
-go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
-go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
-go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
-go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
-go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
-go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
-go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
-go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
-go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.69.0 h1:2yEATaop1/a1I4psnSLgWVPLWwCzkqWakgJy7xTDVy0=
+go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.69.0/go.mod h1:D7J12YRapIekYyPWgGPlA/23pRmpSEZC5xJC/TTLI9U=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0/go.mod h1:z9+yiacE0IHRqM4qFfkbt/JYlmYXgss8GY/jXoNuPJI=
+go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
+go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
+go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
+go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
-golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
-golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f h1:W3F4c+6OLc6H2lb//N1q4WpJkhzJCK5J6kUi1NTVXfM=
-golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f/go.mod h1:J1xhfL/vlindoeF/aINzNzt2Bket5bjo9sdOYzOsU80=
-golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
-golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
+golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
+golang.org/x/exp v0.0.0-20260528193900-50dc527dd6c7 h1:cHpkPjp4TILjdZxz/O4ykwCpeS+dDqNuDGse4zgQDCk=
+golang.org/x/exp v0.0.0-20260528193900-50dc527dd6c7/go.mod h1:d2fgXJLVs4dYDHUk5lwMIfzRzSrWCfGZb0ZqeLa/Vcw=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
-golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
-google.golang.org/api v0.277.0 h1:HJfyJUiNeBBUMai7ez8u14wkp/gH/I4wpGbbO9o+cSk=
-google.golang.org/api v0.277.0/go.mod h1:B9TqLBwJqVjp1mtt7WeoQwWRwvu/400y5lETOql+giQ=
-google.golang.org/genai v1.55.0 h1:iLHGk4Bj/IZ/GNNZb7hYqwSJMRBvqLeu2Hb6YQ+rYGw=
-google.golang.org/genai v1.55.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
-google.golang.org/genproto v0.0.0-20260427160629-7cedc36a6bc4 h1:2iMJZntwvmfgtse+s744JY7v7PgEdSBuFYXucvpOHNM=
-google.golang.org/genproto v0.0.0-20260427160629-7cedc36a6bc4/go.mod h1:v14kaaboYyXQ1Gsu489Q+Hg/oN4B33mWtuOhF1HCeXA=
-google.golang.org/genproto/googleapis/api v0.0.0-20260427160629-7cedc36a6bc4 h1:yOzSCGPx+cp5VO7IxvZ9SBFF7j1tZVcNtlHR2iYKtVo=
-google.golang.org/genproto/googleapis/api v0.0.0-20260427160629-7cedc36a6bc4/go.mod h1:Q9HWtNeE7tM9npdIsEvqXj1QJIvVoeAV3rtXtS715Cw=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260427160629-7cedc36a6bc4 h1:tEkOQcXgF6dH1G+MVKZrfpYvozGrzb91k6ha7jireSM=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260427160629-7cedc36a6bc4/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.81.0 h1:W3G9N3KQf3BU+YuCtGKJk0CmxQNbAISICD/9AORxLIw=
-google.golang.org/grpc v1.81.0/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
+google.golang.org/api v0.282.0 h1:WmJiSVqUnKqJCpJOx7YADbXaC+9DDsnGSfllFSj7R2I=
+google.golang.org/api v0.282.0/go.mod h1:6Wssta4c5n9qHq5CBhmlai5h/PUa1djdDAIhYEHyvcM=
+google.golang.org/genai v1.58.0 h1:MNA3ZkRyr7MnRwZ9RNZ60p4+UMKV3yYRw6pyHq4pp0U=
+google.golang.org/genai v1.58.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
+google.golang.org/genproto v0.0.0-20260504160031-60b97b32f348 h1:JjVGDZYWkJWZcxveJGzfkXC5myDVWAd4dZdgbzrDUv8=
+google.golang.org/genproto v0.0.0-20260504160031-60b97b32f348/go.mod h1:95PqD4xM+AdOcBGsmgfaofXsiA37uXDtDufVbntT3TU=
+google.golang.org/genproto/googleapis/api v0.0.0-20260504160031-60b97b32f348 h1:U8orV30l6KpDsi9dxU0CoJZGbjS8EEpw+6ba+XwGPQA=
+google.golang.org/genproto/googleapis/api v0.0.0-20260504160031-60b97b32f348/go.mod h1:Yzdzr5OOZFgSsEV2D/Xi9NL3bszpXFAg0hFJiRohcD8=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa h1:mZHHdPZl0dbGHCflZgAq/Q468DWVFcU2whhB2KAo8fk=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.81.1 h1:VnnIIZ88UzOOKLukQi+ImGz8O1Wdp8nAGGnvOfEIWQQ=
+google.golang.org/grpc v1.81.1/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/acpserver/session.go

@@ -7,6 +7,7 @@ import (
 	"sync"
 
 	"github.com/charmbracelet/log"
+	"github.com/spf13/viper"
 
 	"github.com/mark3labs/kit/internal/extbridge"
 	"github.com/mark3labs/kit/internal/extensions"
@@ -38,10 +39,21 @@ func newSessionRegistry() *sessionRegistry {
 // given working directory. The Kit-generated session ID is used as the ACP
 // session ID so the mapping is 1:1.
 func (r *sessionRegistry) create(ctx context.Context, cwd string) (*acpSession, error) {
+	// Each ACP session gets its own isolated config store (CLI is left nil) so
+	// per-session SetModel / SetThinkingLevel calls cannot race or bleed across
+	// the sessionRegistry. We seed the relevant root-command flag values from
+	// the process-global store (which cobra populated from flags) so launching
+	// `kit acp -m <model> [--thinking-level ...] [--provider-url ...]` is still
+	// honored; .kit.yml and KIT_* env vars are loaded per session by kit.New.
+	streamOn := true
 	kitInstance, err := kit.New(ctx, &kit.Options{
-		SessionDir: cwd,
-		Quiet:      true,
-		Streaming:  true,
+		SessionDir:     cwd,
+		Quiet:          true,
+		Streaming:      &streamOn,
+		Model:          viper.GetString("model"),
+		ThinkingLevel:  viper.GetString("thinking-level"),
+		ProviderURL:    viper.GetString("provider-url"),
+		ProviderAPIKey: viper.GetString("provider-api-key"),
 	})
 	if err != nil {
 		// Provide actionable guidance for provider auth errors, which are

internal/agent/agent.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"strings"
+	"sync"
 	"time"
 
 	"charm.land/fantasy"
@@ -245,6 +246,12 @@ type Agent struct {
 	mcpReady chan struct{}
 	// mcpErr holds any error from background MCP loading.
 	mcpErr error
+
+	// promptMu serializes runtime updates to systemPrompt and the
+	// accompanying fantasy agent rebuild so concurrent SetSystemPrompt
+	// callers (e.g. Kit.applyComposedSystemPrompt invoked from multiple
+	// goroutines) don't race on a.systemPrompt / a.fantasyAgent.
+	promptMu sync.Mutex
 }
 
 // GenerateWithLoopResult contains the result and conversation history from an agent interaction.
@@ -585,8 +592,13 @@ func (a *Agent) GenerateWithCallbacks(ctx context.Context, messages []fantasy.Me
 	// This avoids type conflicts with provider-level options.
 	history = applyCacheControlToMessages(history)
 
-	// Track current tool call args for callbacks
-	var currentToolArgs string
+	// Track tool call args per-ToolCallID so parallel tool calls in a single
+	// step don't clobber each other. Without this, OnToolResult callbacks would
+	// all see the args of the last OnToolCall in the step. The mutex guards
+	// against the possibility that the underlying streaming layer dispatches
+	// callbacks from multiple goroutines.
+	toolCallArgs := make(map[string]string)
+	var toolCallArgsMu sync.Mutex
 
 	// Use the streaming path when streaming is enabled OR when any callbacks are
 	// provided. The agent only exposes tool/step callbacks on AgentStreamCall, so
@@ -773,7 +785,9 @@ func (a *Agent) GenerateWithCallbacks(ctx context.Context, messages []fantasy.Me
 				if ctx.Err() != nil {
 					return ctx.Err()
 				}
-				currentToolArgs = tc.Input
+				toolCallArgsMu.Lock()
+				toolCallArgs[tc.ToolCallID] = tc.Input
+				toolCallArgsMu.Unlock()
 
 				// Notify about the tool call
 				if cb.OnToolCall != nil {
@@ -793,15 +807,22 @@ func (a *Agent) GenerateWithCallbacks(ctx context.Context, messages []fantasy.Me
 				if ctx.Err() != nil {
 					return ctx.Err()
 				}
+				// Look up the args recorded for this specific tool call. Delete
+				// the entry so the map doesn't accumulate across steps.
+				toolCallArgsMu.Lock()
+				args := toolCallArgs[tr.ToolCallID]
+				delete(toolCallArgs, tr.ToolCallID)
+				toolCallArgsMu.Unlock()
+
 				// Notify tool execution finished
 				if cb.OnToolExecution != nil {
-					cb.OnToolExecution(tr.ToolCallID, tr.ToolName, currentToolArgs, false)
+					cb.OnToolExecution(tr.ToolCallID, tr.ToolName, args, false)
 				}
 
 				if cb.OnToolResult != nil {
 					// Extract result text and error status
 					resultText, isError := extractToolResultText(tr)
-					cb.OnToolResult(tr.ToolCallID, tr.ToolName, currentToolArgs, resultText, tr.ClientMetadata, isError)
+					cb.OnToolResult(tr.ToolCallID, tr.ToolName, args, resultText, tr.ClientMetadata, isError)
 				}
 
 				return nil
@@ -1303,6 +1324,24 @@ func (a *Agent) GetModel() fantasy.LanguageModel {
 	return a.model
 }
 
+// SetSystemPrompt updates the agent's system prompt and rebuilds the underlying
+// fantasy agent so subsequent turns use the new prompt. Safe to call while the
+// agent is idle; if invoked during an in-flight turn the new prompt takes
+// effect on the next LLM call.
+func (a *Agent) SetSystemPrompt(prompt string) {
+	a.promptMu.Lock()
+	defer a.promptMu.Unlock()
+	a.systemPrompt = prompt
+	a.rebuildFantasyAgent()
+}
+
+// GetSystemPrompt returns the agent's current system prompt.
+func (a *Agent) GetSystemPrompt() string {
+	a.promptMu.Lock()
+	defer a.promptMu.Unlock()
+	return a.systemPrompt
+}
+
 // GetMaxTokens returns the effective max output tokens the agent currently
 // sends to the LLM provider, after per-model defaults, right-sizing, and any
 // Anthropic thinking-budget adjustments. Returns 0 when no ModelConfig is

internal/agent/agent_parallel_tool_args_test.go

@@ -0,0 +1,109 @@
+package agent
+
+import (
+	"context"
+	"sync"
+	"testing"
+
+	"charm.land/fantasy"
+)
+
+// fakeParallelAgent simulates a provider that emits two parallel tool_use
+// blocks in a single step. It invokes the streaming callbacks in the order:
+//
+//	OnToolCall(A) -> OnToolCall(B) -> OnToolResult(A) -> OnToolResult(B)
+//
+// Before the fix in #33 the agent-layer wrapper recorded a single
+// `currentToolArgs` variable that was clobbered by the second OnToolCall, so
+// both OnToolResult callbacks received B's args instead of their own.
+type fakeParallelAgent struct {
+	calls   []fantasy.ToolCallContent
+	results []fantasy.ToolResultContent
+}
+
+func (f *fakeParallelAgent) Generate(_ context.Context, _ fantasy.AgentCall) (*fantasy.AgentResult, error) {
+	return &fantasy.AgentResult{}, nil
+}
+
+func (f *fakeParallelAgent) Stream(_ context.Context, opts fantasy.AgentStreamCall) (*fantasy.AgentResult, error) {
+	for _, tc := range f.calls {
+		if opts.OnToolCall != nil {
+			if err := opts.OnToolCall(tc); err != nil {
+				return nil, err
+			}
+		}
+	}
+	for _, tr := range f.results {
+		if opts.OnToolResult != nil {
+			if err := opts.OnToolResult(tr); err != nil {
+				return nil, err
+			}
+		}
+	}
+	return &fantasy.AgentResult{}, nil
+}
+
+// TestGenerateWithCallbacks_ParallelToolArgs is the regression test for #33.
+// It drives the streaming-callback wiring inside GenerateWithCallbacks with a
+// fake fantasy.Agent that emits two parallel tool calls before either result.
+// Each OnToolResult must receive the args of its own tool call (matched by
+// ToolCallID), not the args of the last OnToolCall in the step.
+func TestGenerateWithCallbacks_ParallelToolArgs(t *testing.T) {
+	t.Parallel()
+
+	argsA := `{"name":"scheduled_jobs"}`
+	argsB := `{"name":"gmail_trigger"}`
+
+	fake := &fakeParallelAgent{
+		calls: []fantasy.ToolCallContent{
+			{ToolCallID: "kit-A", ToolName: "load_skill", Input: argsA},
+			{ToolCallID: "kit-B", ToolName: "load_skill", Input: argsB},
+		},
+		results: []fantasy.ToolResultContent{
+			{ToolCallID: "kit-A", ToolName: "load_skill", Result: fantasy.ToolResultOutputContentText{Text: "ok-A"}},
+			{ToolCallID: "kit-B", ToolName: "load_skill", Result: fantasy.ToolResultOutputContentText{Text: "ok-B"}},
+		},
+	}
+
+	a := &Agent{
+		fantasyAgent:     fake,
+		streamingEnabled: false, // exercise the "hasCallbacks" branch
+	}
+
+	var mu sync.Mutex
+	resultArgs := map[string]string{}
+	executionArgs := map[string]string{} // captured when running == false
+
+	cb := GenerateCallbacks{
+		OnToolExecution: func(id, _, args string, running bool) {
+			if running {
+				return
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			executionArgs[id] = args
+		},
+		OnToolResult: func(id, _, args, _, _ string, _ bool) {
+			mu.Lock()
+			defer mu.Unlock()
+			resultArgs[id] = args
+		},
+	}
+
+	if _, err := a.GenerateWithCallbacks(context.Background(), nil, cb); err != nil {
+		t.Fatalf("GenerateWithCallbacks returned error: %v", err)
+	}
+
+	if got, want := resultArgs["kit-A"], argsA; got != want {
+		t.Errorf("OnToolResult for kit-A: args = %q, want %q", got, want)
+	}
+	if got, want := resultArgs["kit-B"], argsB; got != want {
+		t.Errorf("OnToolResult for kit-B: args = %q, want %q", got, want)
+	}
+	if got, want := executionArgs["kit-A"], argsA; got != want {
+		t.Errorf("OnToolExecution(finish) for kit-A: args = %q, want %q", got, want)
+	}
+	if got, want := executionArgs["kit-B"], argsB; got != want {
+		t.Errorf("OnToolExecution(finish) for kit-B: args = %q, want %q", got, want)
+	}
+}

internal/auth/credentials.go

@@ -255,29 +255,6 @@ func (cm *CredentialManager) HasAnthropicCredentials() (bool, error) {
 	}
 }
 
-// SetOpenAICredentials stores OpenAI API key credentials. It validates the
-// API key format before storing. The API key must start with "sk-" and be
-// at least 20 characters long. Returns an error if the API key is invalid or
-// if storage fails.
-func (cm *CredentialManager) SetOpenAICredentials(apiKey string) error {
-	if err := validateOpenAIAPIKey(apiKey); err != nil {
-		return err
-	}
-
-	store, err := cm.LoadCredentials()
-	if err != nil {
-		return err
-	}
-
-	store.OpenAI = &OpenAICredentials{
-		Type:      "api_key",
-		APIKey:    apiKey,
-		CreatedAt: time.Now(),
-	}
-
-	return cm.SaveCredentials(store)
-}
-
 // GetOpenAICredentials retrieves stored OpenAI credentials. Returns nil if
 // no credentials are stored. The returned credentials may be either OAuth or API
 // key type, check the Type field to determine which.
@@ -417,26 +394,6 @@ func validateAnthropicAPIKey(apiKey string) error {
 	return nil
 }
 
-// validateOpenAIAPIKey validates the format of an OpenAI API key
-func validateOpenAIAPIKey(apiKey string) error {
-	apiKey = strings.TrimSpace(apiKey)
-
-	if apiKey == "" {
-		return fmt.Errorf("API key cannot be empty")
-	}
-
-	// OpenAI API keys typically start with "sk-" and are quite long
-	if !strings.HasPrefix(apiKey, "sk-") {
-		return fmt.Errorf("invalid OpenAI API key format (should start with 'sk-')")
-	}
-
-	if len(apiKey) < 20 {
-		return fmt.Errorf("API key appears to be too short")
-	}
-
-	return nil
-}
-
 // GetAnthropicAPIKey retrieves an Anthropic API key from multiple sources in priority order:
 // 1. Command-line flag value (highest priority)
 // 2. Stored credentials (OAuth or API key)

internal/config/merger.go

@@ -7,32 +7,48 @@ import (
 	"github.com/spf13/viper"
 )
 
-// LoadAndValidateConfig loads configuration from viper, fixes environment variable
-// casing issues, and validates the configuration. Returns an error if loading or
-// validation fails.
+// LoadAndValidateConfig loads configuration from the process-global viper
+// store, fixes environment variable casing issues, and validates the
+// configuration. Returns an error if loading or validation fails.
+//
+// This is a convenience wrapper around [LoadAndValidateConfigFrom] using the
+// shared global store; it is retained for the CLI and other callers that rely
+// on viper's process-global state.
 func LoadAndValidateConfig() (*Config, error) {
+	return LoadAndValidateConfigFrom(viper.GetViper())
+}
+
+// LoadAndValidateConfigFrom loads configuration from the supplied per-instance
+// store, fixes environment variable casing issues, and validates the
+// configuration. When v is nil, the process-global store is used. Threading an
+// explicit store lets each Kit instance own an isolated configuration without
+// clobbering other instances in the same process.
+func LoadAndValidateConfigFrom(v *viper.Viper) (*Config, error) {
+	if v == nil {
+		v = viper.GetViper()
+	}
 	config := &Config{
 		MCPServers: make(map[string]MCPServerConfig),
 	}
-	if err := viper.Unmarshal(config); err != nil {
-		return nil, fmt.Errorf("failed to unmarshal config: %v", err)
+	if err := v.Unmarshal(config); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal config: %w", err)
 	}
 
 	// Fix environment variable case sensitivity issue
 	// Viper lowercases all keys, but we need to preserve the original case for environment variables
-	fixEnvironmentCase(config)
+	fixEnvironmentCase(v, config)
 
 	if err := config.Validate(); err != nil {
-		return nil, fmt.Errorf("invalid config: %v", err)
+		return nil, fmt.Errorf("invalid config: %w", err)
 	}
 
 	return config, nil
 }
 
 // fixEnvironmentCase fixes the case of environment variable keys that were lowercased by Viper
-func fixEnvironmentCase(config *Config) {
+func fixEnvironmentCase(v *viper.Viper, config *Config) {
 	// Get the raw config data from viper
-	rawConfig := viper.AllSettings()
+	rawConfig := v.AllSettings()
 
 	// Check if we have mcpServers in the raw config
 	if mcpServersRaw, ok := rawConfig["mcpservers"]; ok {

internal/core/bash.go

@@ -160,15 +160,6 @@ func rewriteSudoForStdin(command string) string {
 	return result
 }
 
-// SudoPasswordRequiredResult is a special marker that indicates sudo needs a password.
-// This is stored in tool response metadata to signal the TUI to prompt for password.
-const SudoPasswordRequiredMetadata = `{"sudo_password_required":true}`
-
-// IsSudoPasswordRequiredResult checks if a tool response indicates sudo password is needed.
-func IsSudoPasswordRequiredResult(resp fantasy.ToolResponse) bool {
-	return resp.Metadata == SudoPasswordRequiredMetadata
-}
-
 func executeBash(ctx context.Context, call fantasy.ToolCall, workDir string) (fantasy.ToolResponse, error) {
 	var args bashArgs
 	if err := parseArgs(call.Input, &args); err != nil {

internal/extensions/runner.go

@@ -98,9 +98,20 @@ type Runner struct {
 	disabledTools   map[string]bool           // nil = all tools enabled
 	customEventSubs map[string][]func(string) // inter-extension event bus
 	optionOverrides map[string]string         // runtime option overrides
+	configStore     *viper.Viper              // per-instance config store (nil = global)
 	mu              sync.RWMutex
 }
 
+// SetConfigStore sets the per-instance configuration store used by GetOption
+// to resolve "options.<name>" config values. When unset (nil), GetOption falls
+// back to the process-global viper store. Threading a per-Kit store keeps
+// extension option resolution isolated between Kit instances.
+func (r *Runner) SetConfigStore(v *viper.Viper) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.configStore = v
+}
+
 // ShortcutEntry pairs a shortcut definition with its handler.
 type ShortcutEntry struct {
 	Def     ShortcutDef
@@ -872,7 +883,13 @@ func (r *Runner) GetOption(name string) string {
 
 	// 3. Viper config: options.<name>
 	configKey := "options." + name
-	if v := viper.GetString(configKey); v != "" {
+	r.mu.RLock()
+	store := r.configStore
+	r.mu.RUnlock()
+	if store == nil {
+		store = viper.GetViper()
+	}
+	if v := store.GetString(configKey); v != "" {
 		return v
 	}
 

internal/kitsetup/setup.go

@@ -46,9 +46,9 @@ type AgentSetupOptions struct {
 	ToolWrapper func([]fantasy.AgentTool) []fantasy.AgentTool
 
 	// ProviderConfig, when non-nil, is used directly instead of calling
-	// BuildProviderConfig(). Callers that already hold viperInitMu can
-	// pre-build this and release the lock before calling SetupAgent, so the
-	// slow agent/MCP initialisation runs concurrently with other New() calls.
+	// BuildProviderConfig(). Callers (e.g. Kit.New) pre-build this from their
+	// per-instance config store and pass it here, so the slow agent/MCP
+	// initialisation can run without further config reads.
 	ProviderConfig *models.ProviderConfig
 	// Debug enables debug logging. When zero-value, viper is consulted.
 	// Only meaningful when ProviderConfig is also set.
@@ -75,6 +75,11 @@ type AgentSetupOptions struct {
 	// MCPTaskConfig configures task-augmented tools/call execution. The
 	// zero value preserves historical synchronous-only behaviour.
 	MCPTaskConfig tools.MCPTaskConfig
+	// Viper is the per-instance configuration store. When set, it is used for
+	// any fallback config reads (debug, no-extensions, max-steps, stream,
+	// extension paths) and is attached to the extension runner. When nil, the
+	// process-global viper store is used.
+	Viper *viper.Viper
 }
 
 // AgentSetupResult bundles the created agent and any debug logger so the caller
@@ -87,57 +92,62 @@ type AgentSetupResult struct {
 	ExtRunner *extensions.Runner
 }
 
-// BuildProviderConfig creates a *models.ProviderConfig from the current viper
-// state. All entry points (root, script, SDK) converge through this function.
+// BuildProviderConfig creates a *models.ProviderConfig from the supplied viper
+// store (or the process-global store when v is nil). All entry points (root,
+// script, SDK) converge through this function.
 //
 // Generation parameter pointers (Temperature, TopP, etc.) are only set when
 // the user has explicitly configured them via CLI flag, environment variable,
 // or global config file. This allows per-model defaults from modelSettings
 // and customModels to fill in unset parameters downstream.
-func BuildProviderConfig() (*models.ProviderConfig, string, error) {
-	systemPrompt, err := config.LoadSystemPrompt(viper.GetString("system-prompt"))
+func BuildProviderConfig(v *viper.Viper) (*models.ProviderConfig, string, error) {
+	if v == nil {
+		v = viper.GetViper()
+	}
+	systemPrompt, err := config.LoadSystemPrompt(v.GetString("system-prompt"))
 	if err != nil {
 		return nil, "", fmt.Errorf("failed to load system prompt: %w", err)
 	}
 
-	numGPU := int32(viper.GetInt("num-gpu-layers"))
-	mainGPU := int32(viper.GetInt("main-gpu"))
+	numGPU := int32(v.GetInt("num-gpu-layers"))
+	mainGPU := int32(v.GetInt("main-gpu"))
 
 	cfg := &models.ProviderConfig{
-		ModelString:    viper.GetString("model"),
+		ModelString:    v.GetString("model"),
 		SystemPrompt:   systemPrompt,
-		ProviderAPIKey: viper.GetString("provider-api-key"),
-		ProviderURL:    viper.GetString("provider-url"),
-		MaxTokens:      viper.GetInt("max-tokens"),
-		StopSequences:  viper.GetStringSlice("stop-sequences"),
+		ProviderAPIKey: v.GetString("provider-api-key"),
+		ProviderURL:    v.GetString("provider-url"),
+		MaxTokens:      v.GetInt("max-tokens"),
+		StopSequences:  v.GetStringSlice("stop-sequences"),
 		NumGPU:         &numGPU,
 		MainGPU:        &mainGPU,
-		TLSSkipVerify:  viper.GetBool("tls-skip-verify"),
-		ThinkingLevel:  models.ParseThinkingLevel(viper.GetString("thinking-level")),
+		TLSSkipVerify:  v.GetBool("tls-skip-verify"),
+		ThinkingLevel:  models.ParseThinkingLevel(v.GetString("thinking-level")),
+		ConfigStore:    v,
 	}
 
 	// Only set generation parameter pointers when the user has explicitly
 	// provided a value. This leaves nil pointers for unset params, allowing
 	// per-model defaults (modelSettings / customModels params) to apply.
-	if viper.IsSet("temperature") {
-		v := float32(viper.GetFloat64("temperature"))
-		cfg.Temperature = &v
+	if v.IsSet("temperature") {
+		val := float32(v.GetFloat64("temperature"))
+		cfg.Temperature = &val
 	}
-	if viper.IsSet("top-p") {
-		v := float32(viper.GetFloat64("top-p"))
-		cfg.TopP = &v
+	if v.IsSet("top-p") {
+		val := float32(v.GetFloat64("top-p"))
+		cfg.TopP = &val
 	}
-	if viper.IsSet("top-k") {
-		v := int32(viper.GetInt("top-k"))
-		cfg.TopK = &v
+	if v.IsSet("top-k") {
+		val := int32(v.GetInt("top-k"))
+		cfg.TopK = &val
 	}
-	if viper.IsSet("frequency-penalty") {
-		v := float32(viper.GetFloat64("frequency-penalty"))
-		cfg.FrequencyPenalty = &v
+	if v.IsSet("frequency-penalty") {
+		val := float32(v.GetFloat64("frequency-penalty"))
+		cfg.FrequencyPenalty = &val
 	}
-	if viper.IsSet("presence-penalty") {
-		v := float32(viper.GetFloat64("presence-penalty"))
-		cfg.PresencePenalty = &v
+	if v.IsSet("presence-penalty") {
+		val := float32(v.GetFloat64("presence-penalty"))
+		cfg.PresencePenalty = &val
 	}
 
 	return cfg, systemPrompt, nil
@@ -149,14 +159,21 @@ func SetupAgent(ctx context.Context, opts AgentSetupOptions) (*AgentSetupResult,
 	var modelConfig *models.ProviderConfig
 	var systemPrompt string
 
+	// Resolve the config store: prefer the per-instance store, falling back to
+	// the process-global store.
+	v := opts.Viper
+	if v == nil {
+		v = viper.GetViper()
+	}
+
 	if opts.ProviderConfig != nil {
-		// Pre-built config supplied by caller (e.g. Kit.New after releasing
-		// viperInitMu). Use it directly — no viper reads needed here.
+		// Pre-built config supplied by caller (e.g. Kit.New after building the
+		// per-instance store). Use it directly — no viper reads needed here.
 		modelConfig = opts.ProviderConfig
 		systemPrompt = modelConfig.SystemPrompt
 	} else {
 		var err error
-		modelConfig, systemPrompt, err = BuildProviderConfig()
+		modelConfig, systemPrompt, err = BuildProviderConfig(v)
 		if err != nil {
 			return nil, err
 		}
@@ -164,13 +181,13 @@ func SetupAgent(ctx context.Context, opts AgentSetupOptions) (*AgentSetupResult,
 
 	// Resolve debug / no-extensions / max-steps / streaming: prefer explicit
 	// fields (set when ProviderConfig was pre-built) over viper fallback.
-	debugEnabled := opts.Debug || viper.GetBool("debug")
-	noExtensions := opts.NoExtensions || viper.GetBool("no-extensions")
+	debugEnabled := opts.Debug || v.GetBool("debug")
+	noExtensions := opts.NoExtensions || v.GetBool("no-extensions")
 	maxSteps := opts.MaxSteps
 	if maxSteps == 0 {
-		maxSteps = viper.GetInt("max-steps")
+		maxSteps = v.GetInt("max-steps")
 	}
-	streamingEnabled := opts.StreamingEnabled || viper.GetBool("stream")
+	streamingEnabled := opts.StreamingEnabled || v.GetBool("stream")
 
 	// Create the appropriate debug logger.
 	var debugLogger tools.DebugLogger
@@ -189,7 +206,7 @@ func SetupAgent(ctx context.Context, opts AgentSetupOptions) (*AgentSetupResult,
 	var extCreationOpts extensionCreationOpts
 	if !noExtensions {
 		var extErr error
-		extRunner, extCreationOpts, extErr = loadExtensions()
+		extRunner, extCreationOpts, extErr = loadExtensions(v)
 		if extErr != nil {
 			fmt.Printf("Warning: Failed to load extensions: %v\n", extErr)
 		}
@@ -253,9 +270,14 @@ type extensionCreationOpts struct {
 }
 
 // loadExtensions discovers and loads Yaegi extensions, builds the runner,
-// and returns the tool wrapper/extra tools.
-func loadExtensions() (*extensions.Runner, extensionCreationOpts, error) {
-	extraPaths := viper.GetStringSlice("extension")
+// and returns the tool wrapper/extra tools. The supplied store is used to
+// resolve the "extension" config key and is attached to the runner so
+// extension option lookups stay isolated to this Kit instance.
+func loadExtensions(v *viper.Viper) (*extensions.Runner, extensionCreationOpts, error) {
+	if v == nil {
+		v = viper.GetViper()
+	}
+	extraPaths := v.GetStringSlice("extension")
 	loaded, err := extensions.LoadExtensions(extraPaths)
 	if err != nil {
 		return nil, extensionCreationOpts{}, err
@@ -266,6 +288,7 @@ func loadExtensions() (*extensions.Runner, extensionCreationOpts, error) {
 	}
 
 	runner := extensions.NewRunner(loaded)
+	runner.SetConfigStore(v)
 
 	wrapper := func(tools []fantasy.AgentTool) []fantasy.AgentTool {
 		return extensions.WrapToolsWithExtensions(tools, runner)

internal/models/autoroute_test.go

@@ -0,0 +1,266 @@
+package models
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// TestNpmToWireProtocol documents the wire protocols that the auto-router
+// understands. Provider-specific bundles (azure, bedrock, vercel, openrouter,
+// google-vertex*) are intentionally absent — they have native top-level cases
+// in CreateProvider and never reach the auto-router.
+func TestNpmToWireProtocol(t *testing.T) {
+	want := map[string]wireProtocol{
+		"@ai-sdk/openai":            wireOpenAI,
+		"@ai-sdk/openai-compatible": wireOpenAI,
+		"@ai-sdk/anthropic":         wireAnthropic,
+		"@ai-sdk/google":            wireGoogle,
+	}
+	for npm, wire := range want {
+		if got := npmToWireProtocol[npm]; got != wire {
+			t.Errorf("npmToWireProtocol[%q] = %d, want %d", npm, got, wire)
+		}
+	}
+
+	// Bundle packages must NOT be in the table (regression guard against the
+	// old npmToLLMProvider map that listed 10 entries but only handled 3).
+	for _, npm := range []string{
+		"@ai-sdk/google-vertex",
+		"@ai-sdk/google-vertex/anthropic",
+		"@ai-sdk/amazon-bedrock",
+		"@ai-sdk/azure",
+		"@openrouter/ai-sdk-provider",
+		"@ai-sdk/vercel",
+	} {
+		if _, ok := npmToWireProtocol[npm]; ok {
+			t.Errorf("npmToWireProtocol unexpectedly contains bundle package %q", npm)
+		}
+	}
+}
+
+// newTestRegistry builds a registry containing a single proxy-style provider
+// ("testproxy") with the given default npm, plus one model that carries the
+// given per-model npm override.
+func newTestRegistry(api, defaultNPM, modelID, modelNPMOverride string) *ModelsRegistry {
+	return &ModelsRegistry{
+		providers: map[string]ProviderInfo{
+			"testproxy": {
+				ID:   "testproxy",
+				Name: "Test Proxy",
+				Env:  []string{"TESTPROXY_API_KEY"},
+				NPM:  defaultNPM,
+				API:  api,
+				Models: map[string]ModelInfo{
+					modelID: {
+						ID:          modelID,
+						Name:        modelID,
+						ProviderNPM: modelNPMOverride,
+					},
+				},
+			},
+		},
+	}
+}
+
+// TestAutoRouteProvider_WireRouting verifies that autoRouteProvider routes each
+// npm package to the correct fantasy provider implementation. This is the core
+// regression test for issue #41: previously any npm that resolved to a
+// non-openai/anthropic/openaicompat LLM provider (notably @ai-sdk/google) hit a
+// dead `default` branch and failed with "has no LLM provider mapping".
+func TestAutoRouteProvider_WireRouting(t *testing.T) {
+	tests := []struct {
+		name        string
+		modelID     string
+		defaultNPM  string
+		overrideNPM string
+		// wantType is the concrete fantasy LanguageModel type the model should
+		// be routed to, identified by reflect type string.
+		wantType string
+	}{
+		{
+			name:       "openai-compatible default",
+			modelID:    "test-model",
+			defaultNPM: "@ai-sdk/openai-compatible",
+			wantType:   "openai.languageModel",
+		},
+		{
+			name:        "anthropic override",
+			modelID:     "test-model",
+			defaultNPM:  "@ai-sdk/openai-compatible",
+			overrideNPM: "@ai-sdk/anthropic",
+			wantType:    "anthropic.languageModel",
+		},
+		{
+			name:        "openai (responses) override",
+			modelID:     "gpt-4o",
+			defaultNPM:  "@ai-sdk/openai-compatible",
+			overrideNPM: "@ai-sdk/openai",
+			wantType:    "openai.responsesLanguageModel",
+		},
+		{
+			// The bug: opencode's gemini-* models override the default
+			// openai-compatible npm with @ai-sdk/google.
+			name:        "google override (issue #41)",
+			modelID:     "gemini-3.5-flash",
+			defaultNPM:  "@ai-sdk/openai-compatible",
+			overrideNPM: "@ai-sdk/google",
+			wantType:    "*google.languageModel",
+		},
+		{
+			// Unknown npm but provider has an API URL → openai-compatible fallback.
+			name:       "unknown npm with API URL falls back to openai-compat",
+			modelID:    "test-model",
+			defaultNPM: "@ai-sdk/some-future-thing",
+			wantType:   "openai.languageModel",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			reg := newTestRegistry("https://proxy.example/v1", tt.defaultNPM, tt.modelID, tt.overrideNPM)
+			config := &ProviderConfig{ProviderAPIKey: "test-key"}
+
+			result, err := autoRouteProvider(context.Background(), config, "testproxy", tt.modelID, reg)
+			if err != nil {
+				t.Fatalf("autoRouteProvider returned error: %v", err)
+			}
+			if result == nil || result.Model == nil {
+				t.Fatalf("autoRouteProvider returned nil model")
+			}
+
+			gotType := reflect.TypeOf(result.Model).String()
+			if gotType != tt.wantType {
+				t.Errorf("routed to %s, want %s", gotType, tt.wantType)
+			}
+		})
+	}
+}
+
+// TestAutoRouteProvider_UnknownNpmNoAPI verifies the improved error message for
+// a provider whose npm has no known wire protocol and that has no API URL to
+// fall back on.
+func TestAutoRouteProvider_UnknownNpmNoAPI(t *testing.T) {
+	reg := newTestRegistry("", "@ai-sdk/unmapped", "test-model", "")
+	config := &ProviderConfig{ProviderAPIKey: "test-key"}
+
+	_, err := autoRouteProvider(context.Background(), config, "testproxy", "test-model", reg)
+	if err == nil {
+		t.Fatal("expected error for unknown npm with no API URL, got nil")
+	}
+	if !strings.Contains(err.Error(), "cannot auto-route provider testproxy") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+	if !strings.Contains(err.Error(), "--provider-url") {
+		t.Errorf("error should suggest --provider-url, got: %v", err)
+	}
+}
+
+// TestAutoRouteProvider_UnknownProvider verifies the not-in-database error.
+func TestAutoRouteProvider_UnknownProvider(t *testing.T) {
+	reg := newTestRegistry("https://proxy.example/v1", "@ai-sdk/openai-compatible", "test-model", "")
+	config := &ProviderConfig{ProviderAPIKey: "test-key"}
+
+	_, err := autoRouteProvider(context.Background(), config, "does-not-exist", "test-model", reg)
+	if err == nil {
+		t.Fatal("expected error for unknown provider, got nil")
+	}
+	if !strings.Contains(err.Error(), "not found in model database") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+// TestIsProviderLLMSupported_Google verifies that a provider whose npm is
+// @ai-sdk/google is reported as supported (it now maps to a wire protocol).
+func TestIsProviderLLMSupported_Google(t *testing.T) {
+	info := &ProviderInfo{ID: "testproxy", NPM: "@ai-sdk/google"}
+	if !isProviderLLMSupported("testproxy", info) {
+		t.Error("expected @ai-sdk/google provider to be LLM-supported")
+	}
+}
+
+// TestVersionedBasePath verifies detection of proxy base URLs that already
+// carry an API version segment (which collides with the genai SDK's injected
+// version).
+func TestVersionedBasePath(t *testing.T) {
+	tests := []struct {
+		rawURL string
+		want   string
+	}{
+		{"https://opencode.ai/zen/v1", "/zen/v1"},
+		{"https://opencode.ai/zen/v1/", "/zen/v1"},
+		{"https://example.com/api/v1beta", "/api/v1beta"},
+		{"https://example.com/api/v2alpha", "/api/v2alpha"},
+		{"https://generativelanguage.googleapis.com", ""},
+		{"https://proxy.example/openai", ""},
+		{"", ""},
+	}
+	for _, tt := range tests {
+		if got := versionedBasePath(tt.rawURL); got != tt.want {
+			t.Errorf("versionedBasePath(%q) = %q, want %q", tt.rawURL, got, tt.want)
+		}
+	}
+}
+
+// recordingRoundTripper captures the path of the request it receives.
+type recordingRoundTripper struct{ gotPath string }
+
+func (r *recordingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	r.gotPath = req.URL.Path
+	return &http.Response{
+		StatusCode: 200,
+		Body:       io.NopCloser(strings.NewReader("{}")),
+		Header:     make(http.Header),
+	}, nil
+}
+
+// TestGeminiProxyTransport_StripsInjectedVersion verifies that the transport
+// collapses the genai-injected "/v1beta" segment that follows a proxy base
+// URL which already carries its own version segment. This is the second-order
+// fix that makes opencode/gemini-* actually reach the proxy (issue #41).
+func TestGeminiProxyTransport_StripsInjectedVersion(t *testing.T) {
+	tests := []struct {
+		name     string
+		basePath string
+		reqPath  string
+		wantPath string
+	}{
+		{
+			name:     "strips doubled v1beta after /zen/v1",
+			basePath: "/zen/v1",
+			reqPath:  "/zen/v1/v1beta/models/gemini-3.5-flash:generateContent",
+			wantPath: "/zen/v1/models/gemini-3.5-flash:generateContent",
+		},
+		{
+			name:     "strips doubled v1beta1 after /zen/v1",
+			basePath: "/zen/v1",
+			reqPath:  "/zen/v1/v1beta1/models/gemini-3.5-flash:generateContent",
+			wantPath: "/zen/v1/models/gemini-3.5-flash:generateContent",
+		},
+		{
+			name:     "leaves non-matching path untouched",
+			basePath: "/zen/v1",
+			reqPath:  "/other/v1beta/models/x:generateContent",
+			wantPath: "/other/v1beta/models/x:generateContent",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rec := &recordingRoundTripper{}
+			tr := &geminiProxyTransport{base: rec, basePath: tt.basePath}
+			req, err := http.NewRequest(http.MethodPost, "https://host"+tt.reqPath, nil)
+			if err != nil {
+				t.Fatalf("NewRequest: %v", err)
+			}
+			if _, err := tr.RoundTrip(req); err != nil {
+				t.Fatalf("RoundTrip: %v", err)
+			}
+			if rec.gotPath != tt.wantPath {
+				t.Errorf("forwarded path = %q, want %q", rec.gotPath, tt.wantPath)
+			}
+		})
+	}
+}

internal/models/custom.go

@@ -10,14 +10,24 @@ import (
 
 // loadCustomModelsFromConfig loads custom model definitions from the config file
 // and returns them as a map of model ID -> ModelInfo. Returns nil if no custom
-// models are configured.
+// models are configured. Reads from the process-global viper store (the model
+// registry is a process-global singleton).
 func loadCustomModelsFromConfig() map[string]ModelInfo {
-	if !viper.IsSet("customModels") {
+	return loadCustomModelsFrom(viper.GetViper())
+}
+
+// loadCustomModelsFrom loads custom model definitions from the supplied store.
+// When v is nil the process-global store is used.
+func loadCustomModelsFrom(v *viper.Viper) map[string]ModelInfo {
+	if v == nil {
+		v = viper.GetViper()
+	}
+	if !v.IsSet("customModels") {
 		return nil
 	}
 
 	var customModels map[string]CustomModelConfig
-	if err := viper.UnmarshalKey("customModels", &customModels); err != nil {
+	if err := v.UnmarshalKey("customModels", &customModels); err != nil {
 		log.Printf("Warning: Failed to parse customModels: %v", err)
 		return nil
 	}
@@ -60,15 +70,26 @@ func modelConfigToModelInfo(modelID string, cfg CustomModelConfig) ModelInfo {
 }
 
 // LoadModelSettingsFromConfig loads per-model generation parameter overrides
-// from the config file. Keys are "provider/model" strings. Returns nil if
-// no model settings are configured.
+// from the process-global viper store. Keys are "provider/model" strings.
+// Returns nil if no model settings are configured.
 func LoadModelSettingsFromConfig() map[string]*GenerationParams {
-	if !viper.IsSet("modelSettings") {
+	return LoadModelSettingsFrom(viper.GetViper())
+}
+
+// LoadModelSettingsFrom loads per-model generation parameter overrides from the
+// supplied per-instance store. When v is nil the process-global store is used.
+// Keys are "provider/model" strings. Returns nil if no model settings are
+// configured.
+func LoadModelSettingsFrom(v *viper.Viper) map[string]*GenerationParams {
+	if v == nil {
+		v = viper.GetViper()
+	}
+	if !v.IsSet("modelSettings") {
 		return nil
 	}
 
 	var settings map[string]GenerationParamsConfig
-	if err := viper.UnmarshalKey("modelSettings", &settings); err != nil {
+	if err := v.UnmarshalKey("modelSettings", &settings); err != nil {
 		log.Printf("Warning: Failed to parse modelSettings: %v", err)
 		return nil
 	}
@@ -148,12 +169,17 @@ func ApplyModelSettings(config *ProviderConfig, modelInfo *ModelInfo) {
 		return
 	}
 
+	// Resolve the config store: prefer the per-instance store carried on the
+	// ProviderConfig (set by BuildProviderConfig / Kit.New), falling back to
+	// the process-global store for callers that don't thread one through.
+	store := config.ConfigStore
+
 	// Collect model-level params: modelSettings override > custom model params.
 	// modelSettings takes priority because it's the more specific/intentional config.
 	var params *GenerationParams
 
 	// First check modelSettings from config.
-	if settings := LoadModelSettingsFromConfig(); settings != nil {
+	if settings := LoadModelSettingsFrom(store); settings != nil {
 		modelKey := provider + "/" + modelName
 		if p, ok := settings[modelKey]; ok {
 			params = p
@@ -173,28 +199,28 @@ func ApplyModelSettings(config *ProviderConfig, modelInfo *ModelInfo) {
 	// We check viper.IsSet() which returns true only when the key was
 	// set via CLI flag, environment variable, or config file global section.
 
-	if params.MaxTokens != nil && !isExplicitlySet("max-tokens") {
+	if params.MaxTokens != nil && !isExplicitlySet(store, "max-tokens") {
 		config.MaxTokens = *params.MaxTokens
 	}
-	if params.Temperature != nil && !isExplicitlySet("temperature") {
+	if params.Temperature != nil && !isExplicitlySet(store, "temperature") {
 		config.Temperature = params.Temperature
 	}
-	if params.TopP != nil && !isExplicitlySet("top-p") {
+	if params.TopP != nil && !isExplicitlySet(store, "top-p") {
 		config.TopP = params.TopP
 	}
-	if params.TopK != nil && !isExplicitlySet("top-k") {
+	if params.TopK != nil && !isExplicitlySet(store, "top-k") {
 		config.TopK = params.TopK
 	}
-	if params.FrequencyPenalty != nil && !isExplicitlySet("frequency-penalty") {
+	if params.FrequencyPenalty != nil && !isExplicitlySet(store, "frequency-penalty") {
 		config.FrequencyPenalty = params.FrequencyPenalty
 	}
-	if params.PresencePenalty != nil && !isExplicitlySet("presence-penalty") {
+	if params.PresencePenalty != nil && !isExplicitlySet(store, "presence-penalty") {
 		config.PresencePenalty = params.PresencePenalty
 	}
-	if len(params.StopSequences) > 0 && !isExplicitlySet("stop-sequences") {
+	if len(params.StopSequences) > 0 && !isExplicitlySet(store, "stop-sequences") {
 		config.StopSequences = params.StopSequences
 	}
-	if params.ThinkingLevel != "" && !isExplicitlySet("thinking-level") {
+	if params.ThinkingLevel != "" && !isExplicitlySet(store, "thinking-level") {
 		config.ThinkingLevel = params.ThinkingLevel
 	}
 	if params.SystemPrompt != "" && config.SystemPrompt == "" {
@@ -228,7 +254,14 @@ func LoadSystemPromptValue(input string) string {
 // isExplicitlySet returns true when the user has explicitly set a config key
 // via CLI flag, environment variable, or the global section of the config file.
 // Model-level defaults should not override explicitly set values.
-func isExplicitlySet(key string) bool {
+//
+// The check runs against the supplied per-instance store when non-nil,
+// otherwise the process-global store. This keeps the "explicit vs unset"
+// precedence contract per-Kit-instance once a store is threaded through.
+func isExplicitlySet(v *viper.Viper, key string) bool {
+	if v == nil {
+		v = viper.GetViper()
+	}
 	// viper.IsSet returns true if the key has been set in any of the
 	// data stores (flag, env, config file, default). We need to check
 	// whether the value was set at the global config level (not just
@@ -239,7 +272,7 @@ func isExplicitlySet(key string) bool {
 	// file values. This means global config file values (e.g.
 	// temperature: 0.7 at the top level) will correctly take precedence
 	// over model-level defaults, which is the desired behavior.
-	return viper.IsSet(key)
+	return v.IsSet(key)
 }
 
 // GenerationParams holds per-model generation parameter defaults.

internal/models/modelsdb.go

@@ -48,18 +48,28 @@ type modelsDBLimit struct {
 	Output  int `json:"output"`
 }
 
-// npmToLLMProvider maps npm package names from models.dev to LLM
-// provider identifiers. Providers not in this map but with an api URL
-// can be auto-routed through openaicompat.
-var npmToLLMProvider = map[string]string{
-	"@ai-sdk/anthropic":               "anthropic",
-	"@ai-sdk/openai":                  "openai",
-	"@ai-sdk/google":                  "google",
-	"@ai-sdk/google-vertex":           "google-vertex",
-	"@ai-sdk/google-vertex/anthropic": "google-vertex-anthropic",
-	"@ai-sdk/amazon-bedrock":          "bedrock",
-	"@ai-sdk/azure":                   "azure",
-	"@openrouter/ai-sdk-provider":     "openrouter",
-	"@ai-sdk/vercel":                  "vercel",
-	"@ai-sdk/openai-compatible":       "openaicompat",
+// wireProtocol identifies which LLM API protocol an npm package speaks.
+// Fantasy implements three native protocols (openai, anthropic, google);
+// everything else in its providers/ tree is a thin wrapper around one of
+// them with a pre-baked default URL or auth scheme.
+type wireProtocol int
+
+const (
+	wireUnknown wireProtocol = iota
+	wireOpenAI
+	wireAnthropic
+	wireGoogle
+)
+
+// npmToWireProtocol maps npm package names from models.dev to the wire
+// protocol they speak. Provider-specific bundles (azure, bedrock, vercel,
+// openrouter, google-vertex, google-vertex-anthropic) are intentionally
+// absent — they have native top-level cases in CreateProvider and never
+// reach the auto-router. Providers not in this map but with an api URL
+// are auto-routed through the OpenAI-compatible wire.
+var npmToWireProtocol = map[string]wireProtocol{
+	"@ai-sdk/openai":            wireOpenAI,
+	"@ai-sdk/openai-compatible": wireOpenAI,
+	"@ai-sdk/anthropic":         wireAnthropic,
+	"@ai-sdk/google":            wireGoogle,
 }

internal/models/providers.go

@@ -9,7 +9,9 @@ import (
 	"io"
 	"maps"
 	"net/http"
+	"net/url"
 	"os"
+	"regexp"
 	"strings"
 	"time"
 
@@ -25,6 +27,7 @@ import (
 	openaisdk "github.com/charmbracelet/openai-go"
 
 	"github.com/mark3labs/kit/internal/auth"
+	"github.com/spf13/viper"
 )
 
 const (
@@ -164,6 +167,13 @@ type ProviderConfig struct {
 	ThinkingLevel    ThinkingLevel
 	DisableCaching   bool // Opt-out: set to true to disable automatic prompt caching
 
+	// ConfigStore is the per-instance configuration store used to resolve
+	// "explicitly set" precedence checks (isExplicitlySet), per-model
+	// settings, and right-sizing. When nil, the process-global viper store is
+	// used. Threading a per-Kit store here keeps generation-parameter
+	// precedence isolated between Kit instances in the same process.
+	ConfigStore *viper.Viper
+
 	// ProgressReaderFunc, when set, wraps an io.Reader with progress display
 	// for long operations like Ollama model pulls. The returned io.ReadCloser
 	// must be closed when done. When nil, the raw reader is consumed directly
@@ -212,8 +222,10 @@ func ParseModelString(modelString string) (provider, model string, err error) {
 //
 // Native providers: anthropic, openai, google, ollama, azure, google-vertex-anthropic,
 // openrouter, bedrock, vercel.
-// Any provider in models.dev with an api URL or openai-compatible npm package
-// is auto-routed through fantasy's openaicompat provider.
+// Any other provider in models.dev is auto-routed by wire protocol: its npm
+// package (or per-model override) selects the OpenAI, Anthropic, or Google
+// transport, using the provider's api URL as the base. Providers with an api
+// URL but an unrecognized npm package fall back to the OpenAI-compatible wire.
 func CreateProvider(ctx context.Context, config *ProviderConfig) (*ProviderResult, error) {
 	provider, modelName, err := ParseModelString(config.ModelString)
 	if err != nil {
@@ -327,43 +339,62 @@ func CreateProvider(ctx context.Context, config *ProviderConfig) (*ProviderResul
 
 // autoRouteProvider attempts to create a provider by looking up its npm package
 // in the models.dev database and routing through the appropriate fantasy provider.
-// For openai-compatible providers, it uses the api URL from models.dev.
-// Models may have a provider override that specifies a different npm package than
-// the provider's default (e.g., opencode's claude-opus-4-6 uses @ai-sdk/anthropic).
+// It routes on wire protocol (openai, anthropic, google) rather than per-npm
+// provider name: fantasy implements three native wire protocols, and every other
+// entry in its providers/ tree is a thin wrapper around one of them. Using the
+// provider's api URL from models.dev as the base URL, any proxy that re-flavors
+// one of these protocols (e.g. opencode's Gemini routes) Just Works.
+//
+// Models may carry a provider override that specifies a different npm package
+// than the provider's default (e.g. opencode's claude-* uses @ai-sdk/anthropic
+// and its gemini-* uses @ai-sdk/google), which is resolved first.
 func autoRouteProvider(ctx context.Context, config *ProviderConfig, provider, modelName string, registry *ModelsRegistry) (*ProviderResult, error) {
 	providerInfo := registry.GetProviderInfo(provider)
 	if providerInfo == nil {
 		return nil, fmt.Errorf("unsupported provider: %s (not found in model database)", provider)
 	}
 
-	// Check for model-specific provider override
+	// Resolve npm: per-model override > provider default.
 	npmPackage := providerInfo.NPM
 	if modelInfo := registry.LookupModel(provider, modelName); modelInfo != nil && modelInfo.ProviderNPM != "" {
 		npmPackage = modelInfo.ProviderNPM
 	}
 
-	// Determine the LLM provider for this npm package
-	llmProvider := npmToLLMProvider[npmPackage]
-	if llmProvider == "" && providerInfo.API != "" {
-		// Unknown npm but has API URL → route through openaicompat
-		llmProvider = "openaicompat"
+	wire, known := npmToWireProtocol[npmPackage]
+	if !known {
+		// Unknown npm but the provider has an API URL → assume OpenAI-compatible.
+		// (Preserves the long-standing "any provider in models.dev with an api URL
+		// is auto-routed through openaicompat" behaviour.)
+		if providerInfo.API == "" {
+			return nil, fmt.Errorf(
+				"cannot auto-route provider %s: npm package %q has no known wire protocol "+
+					"and the registry has no API URL (use --provider-url to override)",
+				provider, npmPackage,
+			)
+		}
+		wire = wireOpenAI
 	}
 
-	switch llmProvider {
-	case "openaicompat":
+	// All three wires use the provider's API URL from models.dev as the base.
+	if config.ProviderURL == "" && providerInfo.API != "" {
+		config.ProviderURL = providerInfo.API
+	}
+
+	switch wire {
+	case wireOpenAI:
+		// The native OpenAI SDK package (@ai-sdk/openai) speaks the Responses
+		// API; openai-compatible proxies (and unknown-npm fallbacks) use the
+		// chat-completions wire via fantasy's openaicompat provider.
+		if npmPackage == "@ai-sdk/openai" {
+			return createAutoRoutedOpenAIProvider(ctx, config, modelName, providerInfo)
+		}
 		return createAutoRoutedOpenAICompatProvider(ctx, config, modelName, providerInfo)
-	case "anthropic":
-		if config.ProviderURL == "" && providerInfo.API != "" {
-			config.ProviderURL = providerInfo.API
-		}
+	case wireAnthropic:
 		return createAutoRoutedAnthropicProvider(ctx, config, modelName, providerInfo)
-	case "openai":
-		if config.ProviderURL == "" && providerInfo.API != "" {
-			config.ProviderURL = providerInfo.API
-		}
-		return createAutoRoutedOpenAIProvider(ctx, config, modelName, providerInfo)
+	case wireGoogle:
+		return createAutoRoutedGoogleProvider(ctx, config, modelName, providerInfo)
 	default:
-		return nil, fmt.Errorf("unsupported provider: %s (npm: %s has no LLM provider mapping)", provider, npmPackage)
+		return nil, fmt.Errorf("internal error: unknown wire protocol for provider %s (npm: %s)", provider, npmPackage)
 	}
 }
 
@@ -480,6 +511,115 @@ func createAutoRoutedOpenAIProvider(ctx context.Context, config *ProviderConfig,
 	return &ProviderResult{Model: model, ProviderOptions: providerOpts}, nil
 }
 
+// createAutoRoutedGoogleProvider creates a Google (Gemini) provider for
+// third-party providers that expose a Gemini-compatible API (e.g. opencode's
+// Gemini routes, which carry an @ai-sdk/google per-model override).
+//
+// The underlying genai SDK always injects its own API version segment
+// ("v1beta") between the base URL and the resource path. When the proxy's
+// base URL from models.dev already carries a version segment (e.g. opencode's
+// https://opencode.ai/zen/v1), that produces a doubled ".../v1/v1beta/..."
+// path that the proxy rejects. In that case we install a transport that
+// strips the injected segment so the proxy's own version is used.
+func createAutoRoutedGoogleProvider(ctx context.Context, config *ProviderConfig, modelName string, info *ProviderInfo) (*ProviderResult, error) {
+	apiKey := resolveAPIKey(config.ProviderAPIKey, info.Env)
+	if apiKey == "" {
+		return nil, fmt.Errorf("%s API key not provided. Use --provider-api-key or set %s",
+			info.Name, strings.Join(info.Env, " / "))
+	}
+
+	opts := []google.Option{
+		google.WithGeminiAPIKey(apiKey),
+		google.WithName(info.ID),
+	}
+
+	if config.ProviderURL != "" {
+		opts = append(opts, google.WithBaseURL(config.ProviderURL))
+	}
+
+	// Decide whether the genai-injected version segment needs stripping.
+	var httpClient *http.Client
+	if basePath := versionedBasePath(config.ProviderURL); basePath != "" {
+		httpClient = newGeminiProxyHTTPClient(basePath, config.TLSSkipVerify)
+	} else if config.TLSSkipVerify {
+		httpClient = createHTTPClientWithTLSConfig(true)
+	}
+	if httpClient != nil {
+		opts = append(opts, google.WithHTTPClient(httpClient))
+	}
+
+	p, err := google.New(opts...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create %s provider: %w", info.Name, err)
+	}
+
+	model, err := p.LanguageModel(ctx, modelName)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create %s model: %w", info.Name, err)
+	}
+
+	return &ProviderResult{Model: model}, nil
+}
+
+// versionSegmentRe matches a trailing API version segment in a URL path,
+// e.g. "/v1", "/v1beta", "/v1beta1", "/v2alpha".
+var versionSegmentRe = regexp.MustCompile(`/v\d+(?:beta\d*|alpha\d*)?$`)
+
+// versionedBasePath returns the path component of rawURL when that path ends
+// with an API version segment (e.g. opencode's ".../zen/v1" → "/zen/v1").
+// It returns "" when rawURL is empty, unparseable, or has no version suffix
+// — in which case the genai SDK's default version injection is correct and
+// no rewriting is needed.
+func versionedBasePath(rawURL string) string {
+	if rawURL == "" {
+		return ""
+	}
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return ""
+	}
+	path := strings.TrimSuffix(u.Path, "/")
+	if versionSegmentRe.MatchString(path) {
+		return path
+	}
+	return ""
+}
+
+// newGeminiProxyHTTPClient builds an HTTP client whose transport strips the
+// genai-injected version segment ("v1beta"/"v1beta1") that directly follows
+// basePath, collapsing "{basePath}/v1beta/..." back to "{basePath}/...".
+func newGeminiProxyHTTPClient(basePath string, skipVerify bool) *http.Client {
+	var base http.RoundTripper
+	if skipVerify {
+		base = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}
+	} else {
+		base = http.DefaultTransport
+	}
+	return &http.Client{
+		Transport: &geminiProxyTransport{base: base, basePath: basePath},
+	}
+}
+
+// geminiProxyTransport removes the redundant API version segment that the
+// genai SDK injects after a proxy base URL that already carries its own
+// version segment.
+type geminiProxyTransport struct {
+	base     http.RoundTripper
+	basePath string
+}
+
+func (t *geminiProxyTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	for _, injected := range []string{"/v1beta1", "/v1beta"} {
+		prefix := t.basePath + injected + "/"
+		if strings.HasPrefix(req.URL.Path, prefix) {
+			newReq := req.Clone(req.Context())
+			newReq.URL.Path = t.basePath + strings.TrimPrefix(req.URL.Path, t.basePath+injected)
+			return t.base.RoundTrip(newReq)
+		}
+	}
+	return t.base.RoundTrip(req)
+}
+
 // resolveAPIKey returns the first non-empty API key from the explicit key
 // or the environment variables.
 func resolveAPIKey(explicitKey string, envVars []string) string {
@@ -530,7 +670,7 @@ func rightSizeMaxTokens(config *ProviderConfig, modelInfo *ModelInfo) {
 	if modelInfo == nil || modelInfo.Limit.Output <= 0 {
 		return
 	}
-	if isExplicitlySet("max-tokens") {
+	if isExplicitlySet(config.ConfigStore, "max-tokens") {
 		return
 	}
 	target := min(modelInfo.Limit.Output, defaultRightSizeCap)

internal/models/registry.go

@@ -404,8 +404,8 @@ func isProviderLLMSupported(providerID string, info *ProviderInfo) bool {
 		return true
 	}
 
-	// Check if npm maps to an LLM provider
-	if _, ok := npmToLLMProvider[info.NPM]; ok {
+	// Check if npm maps to a known wire protocol
+	if _, ok := npmToWireProtocol[info.NPM]; ok {
 		return true
 	}
 

internal/tools/connection_pool.go

@@ -345,49 +345,70 @@ func (p *MCPConnectionPool) createStdioClient(ctx context.Context, serverConfig
 	return stdioClient, nil
 }
 
-// createSSEClient creates an SSE client
+// parseHeaders parses "Key: Value" header strings into a map.
+func parseHeaders(raw []string) map[string]string {
+	if len(raw) == 0 {
+		return nil
+	}
+	headers := make(map[string]string)
+	for _, header := range raw {
+		parts := strings.SplitN(header, ":", 2)
+		if len(parts) == 2 {
+			key := strings.TrimSpace(parts[0])
+			value := strings.TrimSpace(parts[1])
+			headers[key] = value
+		}
+	}
+	if len(headers) == 0 {
+		return nil
+	}
+	return headers
+}
+
+// buildOAuthConfig constructs a transport.OAuthConfig from the server config
+// and the pool's OAuth flow. Returns nil if OAuth is not applicable.
+func (p *MCPConnectionPool) buildOAuthConfig(serverConfig config.MCPServerConfig) (*transport.OAuthConfig, error) {
+	if p.oauthFlow == nil || serverConfig.NoOAuth {
+		return nil, nil
+	}
+	tokenStore, err := p.createTokenStore(serverConfig.URL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create token store: %w", err)
+	}
+	cfg := &transport.OAuthConfig{
+		RedirectURI: p.oauthFlow.handler.RedirectURI(),
+		PKCEEnabled: true,
+		TokenStore:  tokenStore,
+	}
+	if serverConfig.OAuthClientID != "" {
+		cfg.ClientID = serverConfig.OAuthClientID
+	}
+	if serverConfig.OAuthClientSecret != "" {
+		cfg.ClientSecret = serverConfig.OAuthClientSecret
+	}
+	if len(serverConfig.OAuthScopes) > 0 {
+		cfg.Scopes = serverConfig.OAuthScopes
+	}
+	return cfg, nil
+}
+
 func (p *MCPConnectionPool) createSSEClient(ctx context.Context, serverConfig config.MCPServerConfig) (client.MCPClient, error) {
 	var options []transport.ClientOption
 
-	if len(serverConfig.Headers) > 0 {
-		headers := make(map[string]string)
-		for _, header := range serverConfig.Headers {
-			parts := strings.SplitN(header, ":", 2)
-			if len(parts) == 2 {
-				key := strings.TrimSpace(parts[0])
-				value := strings.TrimSpace(parts[1])
-				headers[key] = value
-			}
-		}
-		if len(headers) > 0 {
-			options = append(options, transport.WithHeaders(headers))
-		}
+	if headers := parseHeaders(serverConfig.Headers); headers != nil {
+		options = append(options, transport.WithHeaders(headers))
 	}
 
 	// Enable OAuth for remote transports when an auth handler is configured
 	// and the server hasn't opted out via NoOAuth. Public MCP servers (e.g.
 	// PubMed) set NoOAuth to skip dynamic client registration and token
 	// exchange, which would otherwise fail with a 404.
-	if p.oauthFlow != nil && !serverConfig.NoOAuth {
-		tokenStore, tsErr := p.createTokenStore(serverConfig.URL)
-		if tsErr != nil {
-			return nil, fmt.Errorf("failed to create token store: %w", tsErr)
-		}
-		oauthCfg := transport.OAuthConfig{
-			RedirectURI: p.oauthFlow.handler.RedirectURI(),
-			PKCEEnabled: true,
-			TokenStore:  tokenStore,
-		}
-		if serverConfig.OAuthClientID != "" {
-			oauthCfg.ClientID = serverConfig.OAuthClientID
-		}
-		if serverConfig.OAuthClientSecret != "" {
-			oauthCfg.ClientSecret = serverConfig.OAuthClientSecret
-		}
-		if len(serverConfig.OAuthScopes) > 0 {
-			oauthCfg.Scopes = serverConfig.OAuthScopes
-		}
-		options = append(options, transport.WithOAuth(oauthCfg))
+	oauthCfg, err := p.buildOAuthConfig(serverConfig)
+	if err != nil {
+		return nil, err
+	}
+	if oauthCfg != nil {
+		options = append(options, transport.WithOAuth(*oauthCfg))
 	}
 
 	sseClient, err := client.NewSSEMCPClient(serverConfig.URL, options...)
@@ -406,43 +427,18 @@ func (p *MCPConnectionPool) createSSEClient(ctx context.Context, serverConfig co
 func (p *MCPConnectionPool) createStreamableClient(ctx context.Context, serverConfig config.MCPServerConfig) (client.MCPClient, error) {
 	var options []transport.StreamableHTTPCOption
 
-	if len(serverConfig.Headers) > 0 {
-		headers := make(map[string]string)
-		for _, header := range serverConfig.Headers {
-			parts := strings.SplitN(header, ":", 2)
-			if len(parts) == 2 {
-				key := strings.TrimSpace(parts[0])
-				value := strings.TrimSpace(parts[1])
-				headers[key] = value
-			}
-		}
-		if len(headers) > 0 {
-			options = append(options, transport.WithHTTPHeaders(headers))
-		}
+	if headers := parseHeaders(serverConfig.Headers); headers != nil {
+		options = append(options, transport.WithHTTPHeaders(headers))
 	}
 
 	// Enable OAuth for remote transports when an auth handler is configured
 	// and the server hasn't opted out via NoOAuth.
-	if p.oauthFlow != nil && !serverConfig.NoOAuth {
-		tokenStore, tsErr := p.createTokenStore(serverConfig.URL)
-		if tsErr != nil {
-			return nil, fmt.Errorf("failed to create token store: %w", tsErr)
-		}
-		oauthCfg := transport.OAuthConfig{
-			RedirectURI: p.oauthFlow.handler.RedirectURI(),
-			PKCEEnabled: true,
-			TokenStore:  tokenStore,
-		}
-		if serverConfig.OAuthClientID != "" {
-			oauthCfg.ClientID = serverConfig.OAuthClientID
-		}
-		if serverConfig.OAuthClientSecret != "" {
-			oauthCfg.ClientSecret = serverConfig.OAuthClientSecret
-		}
-		if len(serverConfig.OAuthScopes) > 0 {
-			oauthCfg.Scopes = serverConfig.OAuthScopes
-		}
-		options = append(options, transport.WithHTTPOAuth(oauthCfg))
+	oauthCfg, err := p.buildOAuthConfig(serverConfig)
+	if err != nil {
+		return nil, err
+	}
+	if oauthCfg != nil {
+		options = append(options, transport.WithHTTPOAuth(*oauthCfg))
 	}
 
 	streamableClient, err := client.NewStreamableHttpClient(serverConfig.URL, options...)

pkg/kit/README.md

@@ -49,6 +49,36 @@ The SDK behaves identically to the CLI:
 - Respects all environment variables (`KIT_*`)
 - Uses the same defaults as the CLI
 
+Each `kit.New` / `kit.NewAgent` call owns an **isolated configuration store**,
+so constructing multiple Kit instances in the same process is safe — setting
+the model, thinking level, or generation parameters on one never affects
+another, and runtime mutators (`SetModel`, `SetThinkingLevel`) only touch the
+owning instance. This makes subagent spawning and multi-Kit embedding race-free
+without external synchronization.
+
+### Functional options (`NewAgent`)
+
+For simple programmatic setups, `kit.NewAgent` is an ergonomic
+functional-options front door over `kit.New`. Streaming is enabled by default;
+pass `kit.WithStreaming(false)` to opt out.
+
+```go
+host, err := kit.NewAgent(ctx,
+    kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+    kit.WithSystemPrompt("You are a helpful assistant."),
+    kit.WithMaxTokens(8192),
+    kit.WithThinkingLevel("medium"),
+    kit.Ephemeral(), // in-memory session, no persistence
+)
+```
+
+Helpers: `WithModel`, `WithSystemPrompt`, `WithStreaming`, `WithMaxTokens`,
+`WithThinkingLevel`, `WithTools`, `WithExtraTools`, `WithProviderAPIKey`,
+`WithProviderURL`, `WithConfigFile`, `WithDebug`, and `Ephemeral`. `Option` is
+a plain `func(*Options)`, so you can define your own. For fields without a
+`With*` helper (`MCPConfig`, `InProcessMCPServers`, `SessionManager`, MCP task
+tuning) construct an `Options` value and call `kit.New`.
+
 ### Options
 
 You can override specific settings:
@@ -59,7 +89,7 @@ host, err := kit.New(ctx, &kit.Options{
     SystemPrompt: "You are a helpful bot",    // Override system prompt
     ConfigFile:   "/path/to/config.yml",      // Use specific config file
     MaxSteps:     10,                         // Override max steps
-    Streaming:    true,                       // Enable streaming
+    Streaming:    ptrBool(true),               // *bool: nil = unset (default true), &false = off
     Quiet:        true,                       // Suppress debug output
 
     // Session options
@@ -241,6 +271,43 @@ response, _ := host.Prompt(ctx, "What's my name?")
 host.ClearSession()
 ```
 
+### Runtime Skills and Context Files
+
+For multi-tenant chatbots, web services, or any host that needs per-user or
+per-session instructions, the SDK lets you add, remove, and replace skills and
+project context files (e.g. `AGENTS.md`) **after** Kit construction. Every
+mutation recomposes the system prompt and applies it to the agent so the next
+turn picks up the new instructions — no restart required.
+
+```go
+// Add a programmatic skill (no file on disk required).
+host.AddSkill(&kit.Skill{
+    Name:        "polite-french",
+    Description: "Respond in French and always greet the user.",
+    Content:     "Always reply in French. Open every response with 'Bonjour'.",
+})
+
+// Or load one from disk.
+host.LoadAndAddSkill("/var/skills/refund-policy.md")
+
+// Swap per-user AGENTS.md content fetched from your database.
+host.AddContextFileContent(
+    fmt.Sprintf("session://%s/AGENTS.md", userID),
+    rulesFromDB,
+)
+
+// Tear down session-specific state when the user logs off.
+host.RemoveSkill("polite-french")
+host.RemoveContextFile(fmt.Sprintf("session://%s/AGENTS.md", userID))
+
+// Or replace the whole set in one shot.
+host.SetSkills(activeSkillsForUser)
+host.SetContextFiles(activeContextForUser)
+```
+
+Readers (`GetSkills`, `GetContextFiles`) return snapshots, and every mutator
+is safe to call concurrently from multiple goroutines.
+
 ## Re-exported Types
 
 The SDK re-exports message/session/MCP types so you don't need direct internal imports. Agent-configuration types are Kit-owned (not aliases) and use only SDK types in their signatures, so consumers never need to import the underlying LLM-provider package.
@@ -294,6 +361,7 @@ msg  := kit.ConvertFromLLMMessage(lMsg)  // LLMMessage  → SDK Message
 
 - `Kit` - Main SDK type
 - `Options` - Configuration options
+- `Option` - Functional option (`func(*Options)`) for `NewAgent`
 - `Message` - Conversation message with typed content parts
 - `Tool` - Agent tool interface
 - `TurnResult` - Full result from a prompt including usage stats
@@ -301,6 +369,7 @@ msg  := kit.ConvertFromLLMMessage(lMsg)  // LLMMessage  → SDK Message
 ### Key Methods
 
 - `New(ctx, opts)` - Create new Kit instance
+- `NewAgent(ctx, ...Option)` - Create a Kit via functional options (streaming on by default)
 - `Prompt(ctx, message)` - Send message and get response string
 - `PromptResult(ctx, message)` - Send message and get full TurnResult
 - `PromptWithOptions(ctx, message, opts)` - Prompt with per-call options
@@ -312,6 +381,9 @@ msg  := kit.ConvertFromLLMMessage(lMsg)  // LLMMessage  → SDK Message
 - `ClearSession()` - Clear conversation history
 - `GetSessionPath()` - Get session file path
 - `GetSessionID()` - Get session UUID
+- `AddSkill(*Skill)` / `LoadAndAddSkill(path)` / `RemoveSkill(name)` / `SetSkills([])` - Manage skills at runtime
+- `AddContextFile(*ContextFile)` / `AddContextFileContent(path, content)` / `LoadAndAddContextFile(path)` / `RemoveContextFile(path)` / `SetContextFiles([])` - Manage AGENTS.md-style context files at runtime
+- `RefreshSystemPrompt()` - Re-apply the composed system prompt to the agent
 - `Close()` - Clean up resources
 
 ### Options

pkg/kit/config.go

@@ -65,23 +65,46 @@ const sdkDefaultMaxTokens = 8192
 //     which returns models.ThinkingOff.
 //   - sampling params (temperature, top-p, top-k, frequency/presence-penalty):
 //     left as nil pointers so provider libraries apply their own defaults.
-func setSDKDefaults() {
-	viper.SetDefault("model", "anthropic/claude-sonnet-4-5-20250929")
-	viper.SetDefault("system-prompt", defaultSystemPrompt)
-	viper.SetDefault("stream", true)
-	viper.SetDefault("num-gpu-layers", -1)
-	viper.SetDefault("main-gpu", 0)
+func setSDKDefaults(v *viper.Viper) {
+	v.SetDefault("model", "anthropic/claude-sonnet-4-5-20250929")
+	v.SetDefault("system-prompt", defaultSystemPrompt)
+	v.SetDefault("stream", true)
+	v.SetDefault("num-gpu-layers", -1)
+	v.SetDefault("main-gpu", 0)
 }
 
-// InitConfig initializes the viper configuration system.
+// InitConfig initializes the process-global viper configuration system.
 // It searches for config files in standard locations and loads them with
 // environment variable substitution.
 //
 // configFile: explicit config file path (empty = search defaults).
 // debug: if true, print warnings about missing configs to stderr.
+//
+// This wraps [initConfig] using the process-global store and is retained for
+// the CLI, which binds its flags to the global viper.
 func InitConfig(configFile string, debug bool) error {
+	return initConfig(viper.GetViper(), configFile, debug)
+}
+
+// initConfig loads configuration into the supplied per-instance store. When v
+// is nil the process-global store is used.
+func initConfig(v *viper.Viper, configFile string, debug bool) error {
+	if v == nil {
+		v = viper.GetViper()
+	}
+
+	// Configure KIT_* environment overrides unconditionally, before any file
+	// is loaded, so that an explicit config file does not disable env support.
+	// Map hyphenated config keys (e.g. "max-tokens") to underscored env var
+	// names (e.g. KIT_MAX_TOKENS); without this AutomaticEnv looks for
+	// KIT_MAX-TOKENS and silently misses valid overrides. Precedence is
+	// resolved at read time, so calling these before ReadConfig is fine.
+	v.SetEnvPrefix("KIT")
+	v.SetEnvKeyReplacer(strings.NewReplacer("-", "_"))
+	v.AutomaticEnv()
+
 	if configFile != "" {
-		return LoadConfigWithEnvSubstitution(configFile)
+		return loadConfigWithEnvSubstitution(v, configFile)
 	}
 
 	// Ensure a config file exists (create default if none found).
@@ -97,15 +120,15 @@ func InitConfig(configFile string, debug bool) error {
 	}
 
 	// Current directory has higher priority than home directory.
-	viper.AddConfigPath(".")
-	viper.AddConfigPath(home)
+	v.AddConfigPath(".")
+	v.AddConfigPath(home)
 
 	configLoaded := false
 
-	viper.SetConfigName(".kit")
-	if err := viper.ReadInConfig(); err == nil {
-		configPath := viper.ConfigFileUsed()
-		if err := LoadConfigWithEnvSubstitution(configPath); err != nil {
+	v.SetConfigName(".kit")
+	if err := v.ReadInConfig(); err == nil {
+		configPath := v.ConfigFileUsed()
+		if err := loadConfigWithEnvSubstitution(v, configPath); err != nil {
 			if strings.Contains(err.Error(), "environment variable substitution failed") {
 				return fmt.Errorf("error reading config file '%s': %w", configPath, err)
 			}
@@ -118,17 +141,21 @@ func InitConfig(configFile string, debug bool) error {
 		fmt.Fprintf(os.Stderr, "No config file found in current directory or home directory\n")
 	}
 
-	viper.SetEnvPrefix("KIT")
-	// Map hyphenated config keys (e.g. "max-tokens") to underscored env
-	// var names (e.g. KIT_MAX_TOKENS). Without this, AutomaticEnv looks
-	// for KIT_MAX-TOKENS and silently misses valid env overrides.
-	viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_"))
-	viper.AutomaticEnv()
 	return nil
 }
 
-// LoadConfigWithEnvSubstitution loads a config file with ${ENV_VAR} expansion.
+// LoadConfigWithEnvSubstitution loads a config file with ${ENV_VAR} expansion
+// into the process-global viper store.
 func LoadConfigWithEnvSubstitution(configPath string) error {
+	return loadConfigWithEnvSubstitution(viper.GetViper(), configPath)
+}
+
+// loadConfigWithEnvSubstitution loads a config file with ${ENV_VAR} expansion
+// into the supplied per-instance store (or the global store when v is nil).
+func loadConfigWithEnvSubstitution(v *viper.Viper, configPath string) error {
+	if v == nil {
+		v = viper.GetViper()
+	}
 	rawContent, err := os.ReadFile(configPath)
 	if err != nil {
 		return fmt.Errorf("failed to read config file: %w", err)
@@ -146,6 +173,6 @@ func LoadConfigWithEnvSubstitution(configPath string) error {
 	}
 
 	config.SetConfigPath(configPath)
-	viper.SetConfigType(configType)
-	return viper.ReadConfig(strings.NewReader(processedContent))
+	v.SetConfigType(configType)
+	return v.ReadConfig(strings.NewReader(processedContent))
 }

pkg/kit/context_files.go

@@ -0,0 +1,150 @@
+package kit
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// ---------------------------------------------------------------------------
+// Runtime context-file management (Issue #36)
+// ---------------------------------------------------------------------------
+//
+// Project context files (AGENTS.md and friends) are normally auto-discovered
+// during Kit.New() and injected into the system prompt. SDK consumers building
+// multi-tenant chatbots often need to swap context per user/session at runtime
+// without restarting the agent. The methods below provide that surface.
+//
+// Every mutation recomposes the system prompt and applies it to the underlying
+// agent so the next turn sees the updated project context.
+
+// AddContextFile registers a project context file (e.g. an AGENTS.md
+// equivalent) on this Kit instance. The file does not need to exist on
+// disk — Path is treated as an opaque identifier used both for de-duplication
+// and for the "Instructions from: <Path>" header injected into the system
+// prompt. If a context file with the same Path is already loaded the new
+// content replaces it.
+//
+// Returns an error when cf is nil or has an empty Path. AddContextFile is
+// safe to call from any goroutine.
+func (m *Kit) AddContextFile(cf *ContextFile) error {
+	if cf == nil {
+		return fmt.Errorf("AddContextFile: context file is nil")
+	}
+	if cf.Path == "" {
+		return fmt.Errorf("AddContextFile: context file path is required")
+	}
+
+	// Take a defensive copy so later mutations by the caller don't race with
+	// the agent reading the composed prompt.
+	stored := &ContextFile{
+		Path:    cf.Path,
+		Content: strings.TrimSpace(cf.Content),
+	}
+
+	m.runtimeMu.Lock()
+	replaced := false
+	for i, existing := range m.contextFiles {
+		if existing.Path == stored.Path {
+			m.contextFiles[i] = stored
+			replaced = true
+			break
+		}
+	}
+	if !replaced {
+		m.contextFiles = append(m.contextFiles, stored)
+	}
+	m.runtimeMu.Unlock()
+
+	m.applyComposedSystemPrompt()
+	return nil
+}
+
+// AddContextFileContent is a convenience wrapper around [Kit.AddContextFile]
+// that builds the ContextFile from a path and inline content string. Use this
+// when the context originates from a database, API response, or any other
+// non-filesystem source.
+func (m *Kit) AddContextFileContent(path, content string) (*ContextFile, error) {
+	cf := &ContextFile{Path: path, Content: content}
+	if err := m.AddContextFile(cf); err != nil {
+		return nil, err
+	}
+	return cf, nil
+}
+
+// LoadAndAddContextFile reads a file from disk and registers it as a project
+// context file via [Kit.AddContextFile]. The absolute path is stored on the
+// resulting ContextFile.
+func (m *Kit) LoadAndAddContextFile(path string) (*ContextFile, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("LoadAndAddContextFile: %w", err)
+	}
+	abs, absErr := filepath.Abs(path)
+	if absErr != nil {
+		abs = path
+	}
+	cf := &ContextFile{
+		Path:    abs,
+		Content: strings.TrimSpace(string(data)),
+	}
+	if err := m.AddContextFile(cf); err != nil {
+		return nil, err
+	}
+	return cf, nil
+}
+
+// RemoveContextFile removes the context file with the given path and
+// recomposes the system prompt. Returns true when a matching file was found
+// and removed, false otherwise.
+func (m *Kit) RemoveContextFile(path string) bool {
+	m.runtimeMu.Lock()
+	found := false
+	for i, cf := range m.contextFiles {
+		if cf.Path == path {
+			m.contextFiles = append(m.contextFiles[:i], m.contextFiles[i+1:]...)
+			found = true
+			break
+		}
+	}
+	m.runtimeMu.Unlock()
+
+	if !found {
+		return false
+	}
+	m.applyComposedSystemPrompt()
+	return true
+}
+
+// SetContextFiles replaces the active context-file set with the provided
+// slice. Pass nil or an empty slice to clear all context. The system prompt
+// is recomposed and applied. ContextFiles with empty Paths are rejected and
+// no mutation is performed.
+func (m *Kit) SetContextFiles(files []*ContextFile) error {
+	// Validate first so a bad input doesn't partially mutate state.
+	for i, cf := range files {
+		if cf == nil {
+			return fmt.Errorf("SetContextFiles: context file at index %d is nil", i)
+		}
+		if cf.Path == "" {
+			return fmt.Errorf("SetContextFiles: context file at index %d has empty path", i)
+		}
+	}
+
+	// Defensive copies so caller-side mutation cannot race with composition.
+	copied := make([]*ContextFile, len(files))
+	for i, cf := range files {
+		copied[i] = &ContextFile{
+			Path:    cf.Path,
+			Content: strings.TrimSpace(cf.Content),
+		}
+	}
+
+	m.runtimeMu.Lock()
+	m.contextFiles = copied
+	m.runtimeMu.Unlock()
+
+	m.applyComposedSystemPrompt()
+	return nil
+}

pkg/kit/export_test.go

@@ -0,0 +1,22 @@
+package kit
+
+// This file exposes a handful of internal accessors to the external kit_test
+// package. Because it ends in _test.go it is only compiled during testing and
+// is therefore not part of the public SDK surface.
+
+// ConfigValueIsSetForTest reports whether key is explicitly set in this Kit's
+// isolated configuration store. Used by tests to assert the tri-state
+// precedence contract per-instance.
+func (m *Kit) ConfigValueIsSetForTest(key string) bool { return m.v.IsSet(key) }
+
+// ConfigStringForTest returns the string value of key from this Kit's isolated
+// configuration store.
+func (m *Kit) ConfigStringForTest(key string) string { return m.v.GetString(key) }
+
+// ConfigFloatForTest returns the float64 value of key from this Kit's isolated
+// configuration store.
+func (m *Kit) ConfigFloatForTest(key string) float64 { return m.v.GetFloat64(key) }
+
+// ConfigBoolForTest returns the bool value of key from this Kit's isolated
+// configuration store.
+func (m *Kit) ConfigBoolForTest(key string) bool { return m.v.GetBool(key) }

pkg/kit/extension_api.go

@@ -8,55 +8,104 @@ import (
 	"github.com/mark3labs/kit/internal/session"
 )
 
+// ==== Extension Types ====
+//
+// Type aliases for internal extension types exposed through the public
+// ExtensionAPI interface. External SDK consumers can use these without
+// importing internal packages directly.
+
+// ExtensionContext holds the runtime context passed to extensions, including
+// callbacks for printing, sending messages, and accessing session state.
+type ExtensionContext = extensions.Context
+
+// ExtensionWidgetConfig describes a widget registered by an extension.
+type ExtensionWidgetConfig = extensions.WidgetConfig
+
+// ExtensionWidgetPlacement indicates where a widget should be rendered
+// (e.g. above or below the conversation).
+type ExtensionWidgetPlacement = extensions.WidgetPlacement
+
+// ExtensionHeaderFooterConfig describes a header or footer registered by an extension.
+type ExtensionHeaderFooterConfig = extensions.HeaderFooterConfig
+
+// ExtensionEditorConfig configures editor behaviour overrides set by extensions.
+type ExtensionEditorConfig = extensions.EditorConfig
+
+// ExtensionUIVisibility controls which UI elements are visible.
+type ExtensionUIVisibility = extensions.UIVisibility
+
+// ExtensionToolRenderConfig describes custom tool output rendering registered by an extension.
+type ExtensionToolRenderConfig = extensions.ToolRenderConfig
+
+// ExtensionMessageRendererConfig describes custom message rendering registered by an extension.
+type ExtensionMessageRendererConfig = extensions.MessageRendererConfig
+
+// ExtensionSessionMessage represents a single message in the session history
+// as exposed to extensions.
+type ExtensionSessionMessage = extensions.SessionMessage
+
+// ExtensionEntry represents a custom data entry stored by an extension
+// in the session tree.
+type ExtensionEntry = extensions.ExtensionEntry
+
+// ExtensionStatusBarEntry describes a status bar entry registered by an extension.
+type ExtensionStatusBarEntry = extensions.StatusBarEntry
+
+// ExtensionToolInfo describes a tool available to the agent, as seen by extensions.
+type ExtensionToolInfo = extensions.ToolInfo
+
+// ExtensionCommandDef describes a slash command registered by an extension.
+type ExtensionCommandDef = extensions.CommandDef
+
 // ExtensionAPI provides grouped access to all extension-related functionality.
 // This cleans up the main Kit API surface while keeping all extension capabilities available.
 type ExtensionAPI interface {
 	// Context management
-	SetContext(ctx extensions.Context)
-	GetContext() extensions.Context
+	SetContext(ctx ExtensionContext)
+	GetContext() ExtensionContext
 	UpdateContextModel(model string)
 
 	// Widgets
-	SetWidget(config extensions.WidgetConfig)
+	SetWidget(config ExtensionWidgetConfig)
 	RemoveWidget(id string)
-	GetWidgets(placement extensions.WidgetPlacement) []extensions.WidgetConfig
+	GetWidgets(placement ExtensionWidgetPlacement) []ExtensionWidgetConfig
 
 	// Header/Footer
-	SetHeader(config extensions.HeaderFooterConfig)
+	SetHeader(config ExtensionHeaderFooterConfig)
 	RemoveHeader()
-	GetHeader() *extensions.HeaderFooterConfig
-	SetFooter(config extensions.HeaderFooterConfig)
+	GetHeader() *ExtensionHeaderFooterConfig
+	SetFooter(config ExtensionHeaderFooterConfig)
 	RemoveFooter()
-	GetFooter() *extensions.HeaderFooterConfig
+	GetFooter() *ExtensionHeaderFooterConfig
 
 	// Editor
-	SetEditor(config extensions.EditorConfig)
+	SetEditor(config ExtensionEditorConfig)
 	ResetEditor()
-	GetEditor() *extensions.EditorConfig
+	GetEditor() *ExtensionEditorConfig
 
 	// UI Visibility
-	SetUIVisibility(v extensions.UIVisibility)
-	GetUIVisibility() *extensions.UIVisibility
+	SetUIVisibility(v ExtensionUIVisibility)
+	GetUIVisibility() *ExtensionUIVisibility
 
 	// Tool rendering
-	GetToolRenderer(toolName string) *extensions.ToolRenderConfig
-	GetMessageRenderer(name string) *extensions.MessageRendererConfig
+	GetToolRenderer(toolName string) *ExtensionToolRenderConfig
+	GetMessageRenderer(name string) *ExtensionMessageRendererConfig
 
 	// Session data
-	GetSessionMessages() []extensions.SessionMessage
+	GetSessionMessages() []ExtensionSessionMessage
 	AppendEntry(extType, data string) (string, error)
-	GetEntries(extType string) []extensions.ExtensionEntry
+	GetEntries(extType string) []ExtensionEntry
 
 	// Status bar
-	SetStatus(entry extensions.StatusBarEntry)
+	SetStatus(entry ExtensionStatusBarEntry)
 	RemoveStatus(key string)
-	GetStatusEntries() []extensions.StatusBarEntry
+	GetStatusEntries() []ExtensionStatusBarEntry
 
 	// Shortcuts
 	GetShortcuts() map[string]func()
 
 	// Tools
-	GetToolInfos() []extensions.ToolInfo
+	GetToolInfos() []ExtensionToolInfo
 	SetActiveTools(names []string)
 
 	// Options
@@ -71,7 +120,7 @@ type ExtensionAPI interface {
 	EmitBeforeSessionSwitch(switchReason string) (cancelled bool, reason string)
 
 	// Commands
-	Commands() []extensions.CommandDef
+	Commands() []ExtensionCommandDef
 
 	// Lifecycle
 	Reload() error

pkg/kit/extensions_bridge.go

@@ -54,83 +54,51 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 	// Subscribe to SDK events and forward to extension runner so extensions
 	// see lifecycle events from the SDK's runTurn()/generate() path.
 
-	if runner.HasHandlers(extensions.AgentStart) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(TurnStartEvent); ok {
-				_, _ = runner.Emit(extensions.AgentStartEvent{Prompt: ev.Prompt})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.AgentStart, func(ev TurnStartEvent) extensions.Event {
+		return extensions.AgentStartEvent{Prompt: ev.Prompt}
+	})
 
-	if runner.HasHandlers(extensions.MessageStart) {
-		m.Subscribe(func(e Event) {
-			if _, ok := e.(MessageStartEvent); ok {
-				_, _ = runner.Emit(extensions.MessageStartEvent{})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.MessageStart, func(_ MessageStartEvent) extensions.Event {
+		return extensions.MessageStartEvent{}
+	})
 
-	if runner.HasHandlers(extensions.MessageUpdate) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(MessageUpdateEvent); ok {
-				_, _ = runner.Emit(extensions.MessageUpdateEvent{Chunk: ev.Chunk})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.MessageUpdate, func(ev MessageUpdateEvent) extensions.Event {
+		return extensions.MessageUpdateEvent{Chunk: ev.Chunk}
+	})
 
-	if runner.HasHandlers(extensions.MessageEnd) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(MessageEndEvent); ok {
-				_, _ = runner.Emit(extensions.MessageEndEvent{Content: ev.Content})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.MessageEnd, func(ev MessageEndEvent) extensions.Event {
+		return extensions.MessageEndEvent{Content: ev.Content}
+	})
 
 	// Tool output streaming events (observation only).
-	if runner.HasHandlers(extensions.ToolOutput) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(ToolOutputEvent); ok {
-				_, _ = runner.Emit(extensions.ToolOutputEvent{
-					ToolCallID: ev.ToolCallID,
-					ToolName:   ev.ToolName,
-					Chunk:      ev.Chunk,
-					IsStderr:   ev.IsStderr,
-				})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.ToolOutput, func(ev ToolOutputEvent) extensions.Event {
+		return extensions.ToolOutputEvent{
+			ToolCallID: ev.ToolCallID,
+			ToolName:   ev.ToolName,
+			Chunk:      ev.Chunk,
+			IsStderr:   ev.IsStderr,
+		}
+	})
 
 	// Tool call input streaming events — fire as the LLM generates tool arguments.
-	if runner.HasHandlers(extensions.ToolCallInputStart) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(ToolCallStartEvent); ok {
-				_, _ = runner.Emit(extensions.ToolCallInputStartEvent{
-					ToolCallID: ev.ToolCallID,
-					ToolName:   ev.ToolName,
-					ToolKind:   ev.ToolKind,
-				})
-			}
-		})
-	}
-	if runner.HasHandlers(extensions.ToolCallInputDelta) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(ToolCallDeltaEvent); ok {
-				_, _ = runner.Emit(extensions.ToolCallInputDeltaEvent{
-					ToolCallID: ev.ToolCallID,
-					Delta:      ev.Delta,
-				})
-			}
-		})
-	}
-	if runner.HasHandlers(extensions.ToolCallInputEnd) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(ToolCallEndEvent); ok {
-				_, _ = runner.Emit(extensions.ToolCallInputEndEvent{
-					ToolCallID: ev.ToolCallID,
-				})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.ToolCallInputStart, func(ev ToolCallStartEvent) extensions.Event {
+		return extensions.ToolCallInputStartEvent{
+			ToolCallID: ev.ToolCallID,
+			ToolName:   ev.ToolName,
+			ToolKind:   ev.ToolKind,
+		}
+	})
+	bridgeObserve(m, runner, extensions.ToolCallInputDelta, func(ev ToolCallDeltaEvent) extensions.Event {
+		return extensions.ToolCallInputDeltaEvent{
+			ToolCallID: ev.ToolCallID,
+			Delta:      ev.Delta,
+		}
+	})
+	bridgeObserve(m, runner, extensions.ToolCallInputEnd, func(ev ToolCallEndEvent) extensions.Event {
+		return extensions.ToolCallInputEndEvent{
+			ToolCallID: ev.ToolCallID,
+		}
+	})
 
 	if runner.HasHandlers(extensions.AgentEnd) {
 		m.Subscribe(func(e Event) {
@@ -278,54 +246,13 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 	// Extension ContextPrepare → SDK ContextPrepare hook.
 	if runner.HasHandlers(extensions.ContextPrepare) {
 		m.OnContextPrepare(HookPriorityNormal, func(h ContextPrepareHook) *ContextPrepareResult {
-			// Convert LLM message slice to extension ContextMessage slice.
-			// Extract plain text from each message for the extension API.
-			extMsgs := make([]extensions.ContextMessage, len(h.Messages))
-			for i, msg := range h.Messages {
-				var sb strings.Builder
-				for _, part := range msg.Content {
-					if tp, ok := part.(LLMTextPart); ok {
-						sb.WriteString(tp.Text)
-					}
-				}
-				extMsgs[i] = extensions.ContextMessage{
-					Index:   i,
-					Role:    string(msg.Role),
-					Content: sb.String(),
-				}
-			}
-
+			extMsgs := llmToContextMessages(h.Messages)
 			result, _ := runner.Emit(extensions.ContextPrepareEvent{Messages: extMsgs})
 			r, ok := result.(extensions.ContextPrepareResult)
 			if !ok || r.Messages == nil {
 				return nil
 			}
-
-			// Rebuild LLM message slice from extension result.
-			rebuilt := make([]LLMMessage, 0, len(r.Messages))
-			for _, cm := range r.Messages {
-				if cm.Index >= 0 && cm.Index < len(h.Messages) {
-					// Reuse original message (preserves original role and content).
-					rebuilt = append(rebuilt, h.Messages[cm.Index])
-				} else {
-					// New message injected by extension — construct from role + text.
-					role := LLMRoleUser
-					switch cm.Role {
-					case "assistant":
-						role = LLMRoleAssistant
-					case "system":
-						role = LLMRoleSystem
-					case "tool":
-						role = LLMRoleTool
-					}
-					rebuilt = append(rebuilt, LLMMessage{
-						Role:    role,
-						Content: []LLMMessagePart{LLMTextPart{Text: cm.Content}},
-					})
-				}
-			}
-
-			return &ContextPrepareResult{Messages: rebuilt}
+			return &ContextPrepareResult{Messages: contextMessagesToLLM(r.Messages, h.Messages)}
 		})
 	}
 
@@ -359,99 +286,56 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 
 	// --- Step lifecycle observation events ---
 
-	if runner.HasHandlers(extensions.StepStart) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(StepStartEvent); ok {
-				_, _ = runner.Emit(extensions.StepStartEvent{StepNumber: ev.StepNumber})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.StepStart, func(ev StepStartEvent) extensions.Event {
+		return extensions.StepStartEvent{StepNumber: ev.StepNumber}
+	})
 
-	if runner.HasHandlers(extensions.StepFinish) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(StepFinishEvent); ok {
-				_, _ = runner.Emit(extensions.StepFinishEvent{
-					StepNumber:       ev.StepNumber,
-					HasToolCalls:     ev.HasToolCalls,
-					FinishReason:     ev.FinishReason,
-					InputTokens:      ev.Usage.InputTokens,
-					OutputTokens:     ev.Usage.OutputTokens,
-					CacheReadTokens:  ev.Usage.CacheReadTokens,
-					CacheWriteTokens: ev.Usage.CacheCreationTokens,
-				})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.StepFinish, func(ev StepFinishEvent) extensions.Event {
+		return extensions.StepFinishEvent{
+			StepNumber:       ev.StepNumber,
+			HasToolCalls:     ev.HasToolCalls,
+			FinishReason:     ev.FinishReason,
+			InputTokens:      ev.Usage.InputTokens,
+			OutputTokens:     ev.Usage.OutputTokens,
+			CacheReadTokens:  ev.Usage.CacheReadTokens,
+			CacheWriteTokens: ev.Usage.CacheCreationTokens,
+		}
+	})
 
-	if runner.HasHandlers(extensions.ReasoningStart) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(ReasoningStartEvent); ok {
-				_, _ = runner.Emit(extensions.ReasoningStartEvent{ID: ev.ID})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.ReasoningStart, func(ev ReasoningStartEvent) extensions.Event {
+		return extensions.ReasoningStartEvent{ID: ev.ID}
+	})
 
-	if runner.HasHandlers(extensions.Warnings) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(WarningsEvent); ok {
-				_, _ = runner.Emit(extensions.WarningsEvent{Warnings: ev.Warnings})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.Warnings, func(ev WarningsEvent) extensions.Event {
+		return extensions.WarningsEvent{Warnings: ev.Warnings}
+	})
 
-	if runner.HasHandlers(extensions.Source) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(SourceEvent); ok {
-				_, _ = runner.Emit(extensions.SourceEvent{
-					SourceType: ev.SourceType,
-					ID:         ev.ID,
-					URL:        ev.URL,
-					Title:      ev.Title,
-				})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.Source, func(ev SourceEvent) extensions.Event {
+		return extensions.SourceEvent{
+			SourceType: ev.SourceType,
+			ID:         ev.ID,
+			URL:        ev.URL,
+			Title:      ev.Title,
+		}
+	})
 
-	if runner.HasHandlers(extensions.Error) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(ErrorEvent); ok {
-				_, _ = runner.Emit(extensions.ErrorEvent{Error: ev.Error.Error()})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.Error, func(ev ErrorEvent) extensions.Event {
+		return extensions.ErrorEvent{Error: ev.Error.Error()}
+	})
 
-	if runner.HasHandlers(extensions.Retry) {
-		m.Subscribe(func(e Event) {
-			if ev, ok := e.(RetryEvent); ok {
-				_, _ = runner.Emit(extensions.RetryEvent{
-					Attempt: ev.Attempt,
-					Error:   ev.Error.Error(),
-				})
-			}
-		})
-	}
+	bridgeObserve(m, runner, extensions.Retry, func(ev RetryEvent) extensions.Event {
+		return extensions.RetryEvent{
+			Attempt: ev.Attempt,
+			Error:   ev.Error.Error(),
+		}
+	})
 
 	// --- PrepareStep hook ---
 	// Extension PrepareStep → SDK PrepareStep hook.
 	// Same pattern as ContextPrepare: convert LLMMessage ↔ ContextMessage.
 	if runner.HasHandlers(extensions.PrepareStep) {
 		m.OnPrepareStep(HookPriorityNormal, func(h PrepareStepHook) *PrepareStepResult {
-			// Convert LLM message slice to extension ContextMessage slice.
-			extMsgs := make([]extensions.ContextMessage, len(h.Messages))
-			for i, msg := range h.Messages {
-				var sb strings.Builder
-				for _, part := range msg.Content {
-					if tp, ok := part.(LLMTextPart); ok {
-						sb.WriteString(tp.Text)
-					}
-				}
-				extMsgs[i] = extensions.ContextMessage{
-					Index:   i,
-					Role:    string(msg.Role),
-					Content: sb.String(),
-				}
-			}
-
+			extMsgs := llmToContextMessages(h.Messages)
 			result, _ := runner.Emit(extensions.PrepareStepEvent{
 				StepNumber: h.StepNumber,
 				Messages:   extMsgs,
@@ -460,30 +344,71 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 			if !ok || r.Messages == nil {
 				return nil
 			}
-
-			// Rebuild LLM message slice from extension result.
-			rebuilt := make([]LLMMessage, 0, len(r.Messages))
-			for _, cm := range r.Messages {
-				if cm.Index >= 0 && cm.Index < len(h.Messages) {
-					rebuilt = append(rebuilt, h.Messages[cm.Index])
-				} else {
-					role := LLMRoleUser
-					switch cm.Role {
-					case "assistant":
-						role = LLMRoleAssistant
-					case "system":
-						role = LLMRoleSystem
-					case "tool":
-						role = LLMRoleTool
-					}
-					rebuilt = append(rebuilt, LLMMessage{
-						Role:    role,
-						Content: []LLMMessagePart{LLMTextPart{Text: cm.Content}},
-					})
-				}
-			}
-
-			return &PrepareStepResult{Messages: rebuilt}
+			return &PrepareStepResult{Messages: contextMessagesToLLM(r.Messages, h.Messages)}
 		})
 	}
 }
+
+// bridgeObserve subscribes to SDK events of type In and forwards them to the
+// extension runner as the event returned by conv. The subscription is only
+// registered when the runner has handlers for the given event kind.
+func bridgeObserve[In Event](m *Kit, runner *extensions.Runner, kind extensions.EventType, conv func(In) extensions.Event) {
+	if !runner.HasHandlers(kind) {
+		return
+	}
+	m.Subscribe(func(e Event) {
+		if ev, ok := e.(In); ok {
+			_, _ = runner.Emit(conv(ev))
+		}
+	})
+}
+
+// llmToContextMessages converts a slice of LLM messages to extension
+// ContextMessage values, extracting plain text from each message.
+func llmToContextMessages(msgs []LLMMessage) []extensions.ContextMessage {
+	extMsgs := make([]extensions.ContextMessage, len(msgs))
+	for i, msg := range msgs {
+		var sb strings.Builder
+		for _, part := range msg.Content {
+			if tp, ok := part.(LLMTextPart); ok {
+				sb.WriteString(tp.Text)
+			}
+		}
+		extMsgs[i] = extensions.ContextMessage{
+			Index:   i,
+			Role:    string(msg.Role),
+			Content: sb.String(),
+		}
+	}
+	return extMsgs
+}
+
+// contextMessagesToLLM rebuilds an LLM message slice from extension
+// ContextMessages. Messages with a valid index reuse the original from
+// originals; new messages injected by extensions are constructed from
+// role + text.
+func contextMessagesToLLM(cms []extensions.ContextMessage, originals []LLMMessage) []LLMMessage {
+	rebuilt := make([]LLMMessage, 0, len(cms))
+	for _, cm := range cms {
+		if cm.Index >= 0 && cm.Index < len(originals) {
+			// Reuse original message (preserves original role and content).
+			rebuilt = append(rebuilt, originals[cm.Index])
+		} else {
+			// New message injected by extension — construct from role + text.
+			role := LLMRoleUser
+			switch cm.Role {
+			case "assistant":
+				role = LLMRoleAssistant
+			case "system":
+				role = LLMRoleSystem
+			case "tool":
+				role = LLMRoleTool
+			}
+			rebuilt = append(rebuilt, LLMMessage{
+				Role:    role,
+				Content: []LLMMessagePart{LLMTextPart{Text: cm.Content}},
+			})
+		}
+	}
+	return rebuilt
+}

pkg/kit/kit.go

@@ -53,6 +53,14 @@ type Kit struct {
 	opts           *Options       // stored for reload operations (skills, etc.)
 	mcpConfig      *config.Config // loaded MCP/server config, shared with subagents
 
+	// v is this Kit instance's isolated configuration store. Each Kit owns its
+	// own *viper.Viper (constructed via viper.New) so that runtime config
+	// mutators (SetModel, SetThinkingLevel) and config reads do not clobber or
+	// observe state from other Kit instances in the same process. When the CLI
+	// constructs a Kit (Options.CLI != nil) this points at the process-global
+	// store so cobra flag bindings remain in effect.
+	v *viper.Viper
+
 	// hasCustomSystemPrompt is true when the user explicitly configured a
 	// system prompt (via --system-prompt flag, config file, or SDK option).
 	// When false, per-model system prompts from modelSettings/customModels
@@ -61,6 +69,11 @@ type Kit struct {
 	// 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
+	// basePrompt holds the resolved base system prompt text (post file-load,
+	// pre runtime-context composition) captured during New. Used by
+	// RefreshSystemPrompt to recompose after skills/context-file mutations.
+	// Protected by runtimeMu.
+	basePrompt string
 
 	// Hook registries — interception layer (see hooks.go).
 	beforeToolCall  *hookRegistry[BeforeToolCallHook, BeforeToolCallResult]
@@ -90,6 +103,12 @@ type Kit struct {
 		mu     sync.RWMutex
 	}
 
+	// runtimeMu protects contextFiles and skills against concurrent runtime
+	// mutations via AddSkill / RemoveSkill / AddContextFile etc. The fields
+	// are read by composeSystemPrompt and several other accessors, so all
+	// reads and writes after Kit construction must take this lock.
+	runtimeMu sync.RWMutex
+
 	// steerCh is a buffered channel used to inject steering messages into
 	// the running agent turn via the LLM library's PrepareStep. Created fresh for
 	// each generate() call and set to nil when idle. Protected by steerMu.
@@ -544,8 +563,8 @@ func (m *Kit) SetModel(ctx context.Context, modelString string) error {
 
 	// Build a provider config from current settings, overriding the model.
 	// Load system prompt properly (handles both file paths and inline content).
-	systemPrompt, _ := config.LoadSystemPrompt(viper.GetString("system-prompt"))
-	thinkingLevel := models.ParseThinkingLevel(viper.GetString("thinking-level"))
+	systemPrompt, _ := config.LoadSystemPrompt(m.v.GetString("system-prompt"))
+	thinkingLevel := models.ParseThinkingLevel(m.v.GetString("thinking-level"))
 
 	// Validate and adjust thinking level for the target model.
 	// Some models (e.g., OpenAI gpt-5.4) don't support "minimal" and require "none".
@@ -556,8 +575,8 @@ func (m *Kit) SetModel(ctx context.Context, modelString string) error {
 			if !models.IsValidThinkingLevelForModel(thinkingLevel, modelName) {
 				fallback := models.SuggestThinkingLevelFallback(thinkingLevel, modelName)
 				if fallback != models.ThinkingOff {
-					// Adjust the thinking level in viper so the change persists.
-					viper.Set("thinking-level", string(fallback))
+					// Adjust the thinking level in the instance store so the change persists.
+					m.v.Set("thinking-level", string(fallback))
 					thinkingLevel = fallback
 				}
 			}
@@ -569,35 +588,36 @@ func (m *Kit) SetModel(ctx context.Context, modelString string) error {
 	cfg := &models.ProviderConfig{
 		ModelString:    modelString,
 		SystemPrompt:   systemPrompt,
-		ProviderAPIKey: viper.GetString("provider-api-key"),
-		ProviderURL:    viper.GetString("provider-url"),
-		MaxTokens:      viper.GetInt("max-tokens"),
-		TLSSkipVerify:  viper.GetBool("tls-skip-verify"),
+		ProviderAPIKey: m.v.GetString("provider-api-key"),
+		ProviderURL:    m.v.GetString("provider-url"),
+		MaxTokens:      m.v.GetInt("max-tokens"),
+		TLSSkipVerify:  m.v.GetBool("tls-skip-verify"),
 		ThinkingLevel:  thinkingLevel,
 		DisableCaching: false, // Caching enabled by default, works with thinking
+		ConfigStore:    m.v,
 	}
 
 	// Only set generation parameter pointers when the user has explicitly
 	// provided a value. This leaves nil pointers for unset params, allowing
 	// per-model defaults (modelSettings / customModels params) to apply.
-	if viper.IsSet("temperature") {
-		v := float32(viper.GetFloat64("temperature"))
+	if m.v.IsSet("temperature") {
+		v := float32(m.v.GetFloat64("temperature"))
 		cfg.Temperature = &v
 	}
-	if viper.IsSet("top-p") {
-		v := float32(viper.GetFloat64("top-p"))
+	if m.v.IsSet("top-p") {
+		v := float32(m.v.GetFloat64("top-p"))
 		cfg.TopP = &v
 	}
-	if viper.IsSet("top-k") {
-		v := int32(viper.GetInt("top-k"))
+	if m.v.IsSet("top-k") {
+		v := int32(m.v.GetInt("top-k"))
 		cfg.TopK = &v
 	}
-	if viper.IsSet("frequency-penalty") {
-		v := float32(viper.GetFloat64("frequency-penalty"))
+	if m.v.IsSet("frequency-penalty") {
+		v := float32(m.v.GetFloat64("frequency-penalty"))
 		cfg.FrequencyPenalty = &v
 	}
-	if viper.IsSet("presence-penalty") {
-		v := float32(viper.GetFloat64("presence-penalty"))
+	if m.v.IsSet("presence-penalty") {
+		v := float32(m.v.GetFloat64("presence-penalty"))
 		cfg.PresencePenalty = &v
 	}
 
@@ -653,18 +673,25 @@ func (m *Kit) GetSystemPromptSource() string {
 // 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.
+// It acquires a read lock on runtimeMu while snapshotting contextFiles and
+// skills, so callers must not hold the write lock.
 func (m *Kit) composeSystemPrompt(basePrompt string) string {
 	cwd, _ := os.Getwd()
 	pb := skills.NewPromptBuilder(basePrompt)
 
+	m.runtimeMu.RLock()
+	contextFiles := append([]*ContextFile(nil), m.contextFiles...)
+	loadedSkills := append([]*skills.Skill(nil), m.skills...)
+	m.runtimeMu.RUnlock()
+
 	// Inject AGENTS.md content as project context.
-	for _, cf := range m.contextFiles {
+	for _, cf := range contextFiles {
 		pb.WithSection("", fmt.Sprintf("Instructions from: %s\n\n%s", cf.Path, cf.Content))
 	}
 
 	// Inject skills metadata.
-	if len(m.skills) > 0 {
-		pb.WithSkills(m.skills)
+	if len(loadedSkills) > 0 {
+		pb.WithSkills(loadedSkills)
 	}
 
 	// Append current date/time and working directory.
@@ -716,7 +743,7 @@ func (m *Kit) ReloadExtensions() error {
 	}
 
 	// Re-load from disk.
-	extraPaths := viper.GetStringSlice("extension")
+	extraPaths := m.v.GetStringSlice("extension")
 	loaded, err := extensions.LoadExtensions(extraPaths)
 	if err != nil {
 		return fmt.Errorf("reloading extensions: %w", err)
@@ -724,6 +751,7 @@ func (m *Kit) ReloadExtensions() error {
 
 	// Swap extensions on the runner (clears dynamic state).
 	m.extRunner.Reload(loaded)
+	m.extRunner.SetConfigStore(m.v)
 
 	// Update extension tools on the agent so the LLM sees changes.
 	if m.agent != nil {
@@ -762,7 +790,8 @@ func (m *Kit) ExecuteCompletion(ctx context.Context, req extensions.CompleteRequ
 		// Create a temporary provider for the requested model.
 		config := &models.ProviderConfig{
 			ModelString:   req.Model,
-			TLSSkipVerify: viper.GetBool("tls-skip-verify"),
+			TLSSkipVerify: m.v.GetBool("tls-skip-verify"),
+			ConfigStore:   m.v,
 		}
 		if req.MaxTokens > 0 {
 			config.MaxTokens = req.MaxTokens
@@ -848,37 +877,30 @@ func (m *Kit) ExecuteCompletion(ctx context.Context, req extensions.CompleteRequ
 // prompts, configuration, and behavior settings. All fields are optional
 // and will use CLI defaults if not specified.
 //
-// Global viper state warning:
-// Options are applied by [New] via [viper.Set] calls against viper's
-// process-global store. This store is shared with every downstream reader
-// (e.g. [Kit.SetModel], [Kit.GetThinkingLevel], BuildProviderConfig, and
-// any other code path that calls viper.Get*). Two consequences:
-//
-//  1. Kit instances are NOT isolated from each other within a single
-//     process. Values set by the second New() call overwrite the first,
-//     and any code that later reads viper will see the most recent Set.
-//  2. Fields left at the zero value do NOT clear prior viper state; they
-//     simply skip the viper.Set. Callers that need a clean slate between
-//     constructions should invoke viper.Reset() (the test suite uses a
-//     private resetViper() helper that wraps it) before the next New().
-//
-// Recommended usage: create one Kit per process, or reset viper between
-// constructions. Concurrent calls to New are serialized internally by
-// [viperInitMu], but that mutex does not prevent later viper reads (from
-// a different Kit) from observing mutated keys.
-//
-// TODO: refactor New to use a per-instance *viper.Viper (constructed via
-// viper.New()) so each Kit owns its own isolated config store and Options
-// no longer leak through the global singleton.
+// Config isolation: each [New] / [NewAgent] call constructs its own isolated
+// configuration store (via viper.New internally). Options are applied to that
+// per-instance store, so two Kits constructed in the same process do NOT share
+// or clobber each other's configuration. Runtime mutators ([Kit.SetModel],
+// [Kit.SetThinkingLevel]) and config readers ([Kit.GetThinkingLevel]) operate
+// only on the owning instance. Fields left at their zero value are simply not
+// applied; they fall through to the precedence chain (env → .kit.yml →
+// per-model defaults) resolved within the instance's own store.
 type Options struct {
 	Model        string // Override model (e.g., "anthropic/claude-sonnet-4-5-20250929")
 	SystemPrompt string // Override system prompt
 	ConfigFile   string // Override config file path
 	MaxSteps     int    // Override max steps (0 = use default)
-	Streaming    bool   // Enable streaming (default from config)
-	Quiet        bool   // Suppress debug output
-	Tools        []Tool // Custom tool set. If empty, AllTools() is used.
-	ExtraTools   []Tool // Additional tools added alongside core/MCP/extension tools.
+
+	// Streaming enables or disables streaming output. It is a pointer so the
+	// SDK can distinguish "unset" (nil) from an explicit choice, mirroring the
+	// sampling-parameter fields below. nil leaves streaming to the precedence
+	// chain (env → .kit.yml → default true); a non-nil value forces it. Prefer
+	// [WithStreaming] for the functional-options API.
+	Streaming *bool
+
+	Quiet      bool   // Suppress debug output
+	Tools      []Tool // Custom tool set. If empty, AllTools() is used.
+	ExtraTools []Tool // Additional tools added alongside core/MCP/extension tools.
 
 	// Generation parameters. These override the corresponding values from
 	// .kit.yml / KIT_* environment variables. Leaving a field at its
@@ -1151,40 +1173,40 @@ func InitTreeSession(opts *Options) (*session.TreeManager, error) {
 	return session.CreateTreeSession(sessionDir)
 }
 
-// viperInitMu serializes viper writes during [New]. Viper's global state
-// is not thread-safe, so concurrent calls (e.g. parallel subagent spawns)
-// must not overlap the Set/Get window. Note that this mutex only protects
-// the construction window — it does not isolate long-lived Kit instances
-// from each other. See the "Global viper state warning" on [Options].
-var viperInitMu sync.Mutex
-
 // New creates a Kit instance using the same initialization as the CLI.
 // It loads configuration, initializes MCP servers, creates the LLM model, and
 // sets up the agent for interaction. Returns an error if initialization fails.
 //
-// Global viper state warning: fields on [Options] are applied by calling
-// [viper.Set] on viper's process-global store. As a result, two Kits
-// constructed in the same process are NOT isolated: the second New
-// overwrites viper keys set by the first, and any downstream reader
-// (e.g. [Kit.SetModel], [Kit.GetThinkingLevel]) will observe the most
-// recent value. Callers that need multiple independent Kits should call
-// viper.Reset() between constructions, or avoid constructing more than
-// one Kit per process. Writes during New are serialized by [viperInitMu].
+// Config isolation: New constructs a per-instance configuration store (via
+// viper.New internally) and applies [Options] to it. Two Kits constructed in
+// the same process are therefore fully isolated — neither overwrites the
+// other's model, thinking level, or generation parameters, and runtime
+// mutators ([Kit.SetModel], [Kit.SetThinkingLevel]) only affect the owning
+// instance. This makes subagent spawning and multi-Kit embedding safe without
+// any external synchronization.
 //
-// TODO: refactor to use a per-call viper.New() instance so each Kit owns
-// its own isolated config store and Options stop leaking through the
-// global singleton.
+// CLI integration: when Options.CLI is non-nil the Kit shares the
+// process-global viper store instead of allocating a fresh one, so cobra flag
+// bindings established by the CLI remain in effect. SDK callers leave
+// Options.CLI nil and always get an isolated store.
+//
+// For an ergonomic functional-options front door, see [NewAgent].
 func New(ctx context.Context, opts *Options) (*Kit, error) {
 	if opts == nil {
 		opts = &Options{}
 	}
 
-	// All viper writes (SetSDKDefaults, InitConfig, Set calls, system-prompt
-	// composition) happen under viperInitMu. We also call BuildProviderConfig
-	// here — it's fast (just reads) — so we can capture the full config
-	// snapshot before releasing the lock. The expensive work (MCP loading,
-	// provider creation, session init) then runs outside the lock, allowing
-	// parallel subagent spawns to proceed concurrently.
+	// Construct this Kit's configuration store. SDK callers get a fresh,
+	// isolated *viper.Viper so concurrent constructions never clobber each
+	// other. The CLI (Options.CLI != nil) shares the process-global store so
+	// its cobra flag bindings and pre-loaded config remain visible.
+	var v *viper.Viper
+	if opts.CLI != nil {
+		v = viper.GetViper()
+	} else {
+		v = viper.New()
+	}
+
 	var (
 		providerConfig        *models.ProviderConfig
 		modelString           string
@@ -1194,86 +1216,93 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 		mcpConfig             *config.Config
 		debug                 bool
 		noExtensions          bool
+		disableCoreTools      bool
 		maxSteps              int
 		streaming             bool
 		hasCustomSystemPrompt bool
 		systemPromptSource    string
+		capturedBasePrompt    string
 	)
 
 	if err := func() error {
-		viperInitMu.Lock()
-		defer viperInitMu.Unlock()
+		// Set CLI-equivalent defaults on the instance store. When used as an
+		// SDK (without cobra), these defaults are not registered via flag bindings.
+		setSDKDefaults(v)
 
-		// Set CLI-equivalent defaults for viper. When used as an SDK (without
-		// cobra), these defaults are not registered via flag bindings.
-		setSDKDefaults()
-
-		// Initialize config (loads config files and env vars).
-		// Only initialize if not already done (e.g., by CLI's cobra.OnInitialize).
-		// Check if model is already set, which indicates config was loaded.
+		// Initialize config (loads config files and env vars) into the instance
+		// store. The CLI shares the process-global store, which cobra.OnInitialize
+		// has already populated, so re-running initConfig there is unnecessary;
+		// SDK callers get a fresh isolated store that must be loaded here.
+		// We key off opts.CLI (not a config value) because setSDKDefaults always
+		// seeds "model", which would otherwise mask an empty store.
 		// SkipConfig bypasses .kit.yml file loading (viper defaults and env vars still apply).
-		if !opts.SkipConfig && viper.GetString("model") == "" {
-			if err := InitConfig(opts.ConfigFile, false); err != nil {
+		if !opts.SkipConfig && opts.CLI == nil {
+			if err := initConfig(v, opts.ConfigFile, false); err != nil {
 				return fmt.Errorf("failed to initialize config: %w", err)
 			}
 		}
 
 		// Handle CLI debug mode.
 		if opts.Debug {
-			viper.Set("debug", true)
+			v.Set("debug", true)
 		}
 
-		// Override viper settings with options.
+		// Override instance settings with options.
 		if opts.Model != "" {
-			viper.Set("model", opts.Model)
+			v.Set("model", opts.Model)
 		}
 		if opts.SystemPrompt != "" {
-			viper.Set("system-prompt", opts.SystemPrompt)
+			v.Set("system-prompt", opts.SystemPrompt)
 		}
 		if opts.MaxSteps > 0 {
-			viper.Set("max-steps", opts.MaxSteps)
+			v.Set("max-steps", opts.MaxSteps)
+		}
+		// Only override streaming when the caller explicitly set it. Otherwise
+		// leave the precedence chain (env → config → default true) untouched so a
+		// zero-valued Options does not silently force stream=false.
+		if opts.Streaming != nil {
+			v.Set("stream", *opts.Streaming)
 		}
-		viper.Set("stream", opts.Streaming)
 
 		// Generation parameter overrides. Each Options field, when set,
-		// is pushed into viper here so the existing downstream code
-		// (BuildProviderConfig, SetModel, modelSettings lookups) picks
-		// it up uniformly. Pointer-typed sampling params use viper.Set
-		// only when non-nil so that nil means "leave provider/per-model
-		// default in place" (BuildProviderConfig keys off viper.IsSet).
+		// is pushed into the instance store here so the existing downstream
+		// code (BuildProviderConfig, SetModel, modelSettings lookups) picks
+		// it up uniformly. Pointer-typed sampling params use Set only when
+		// non-nil so that nil means "leave provider/per-model default in
+		// place" (BuildProviderConfig keys off IsSet).
 		if opts.MaxTokens > 0 {
-			viper.Set("max-tokens", opts.MaxTokens)
+			v.Set("max-tokens", opts.MaxTokens)
 		}
 		if opts.ThinkingLevel != "" {
-			viper.Set("thinking-level", opts.ThinkingLevel)
+			v.Set("thinking-level", opts.ThinkingLevel)
 		}
 		if opts.Temperature != nil {
-			viper.Set("temperature", *opts.Temperature)
+			v.Set("temperature", *opts.Temperature)
 		}
 		if opts.TopP != nil {
-			viper.Set("top-p", *opts.TopP)
+			v.Set("top-p", *opts.TopP)
 		}
 		if opts.TopK != nil {
-			viper.Set("top-k", *opts.TopK)
+			v.Set("top-k", *opts.TopK)
 		}
 		if opts.FrequencyPenalty != nil {
-			viper.Set("frequency-penalty", *opts.FrequencyPenalty)
+			v.Set("frequency-penalty", *opts.FrequencyPenalty)
 		}
 		if opts.PresencePenalty != nil {
-			viper.Set("presence-penalty", *opts.PresencePenalty)
+			v.Set("presence-penalty", *opts.PresencePenalty)
 		}
 
 		// Provider overrides. TLSSkipVerify only takes effect when true —
 		// callers wanting to force-disable should use the config file or
 		// env var instead.
 		if opts.ProviderAPIKey != "" {
-			viper.Set("provider-api-key", opts.ProviderAPIKey)
+			v.Set("provider-api-key", opts.ProviderAPIKey)
 		}
 		if opts.ProviderURL != "" {
-			viper.Set("provider-url", opts.ProviderURL)
+			v.Set("provider-url", opts.ProviderURL)
 		}
 		if opts.TLSSkipVerify {
-			viper.Set("tls-skip-verify", true)
+			v.Set("tls-skip-verify", true)
 		}
 
 		// Resolve working directory for context/skill discovery.
@@ -1304,7 +1333,7 @@ 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.
 		{
-			rawPromptInput := viper.GetString("system-prompt")
+			rawPromptInput := v.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,
@@ -1329,12 +1358,12 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 			// Check for per-model system prompt override when no explicit
 			// global system-prompt was configured by the user.
 			if !userSetSystemPrompt {
-				modelStr := viper.GetString("model")
+				modelStr := v.GetString("model")
 				if modelStr != "" {
 					if mi := models.LookupModelForSettings(modelStr); mi != nil {
 						var perModelParams *models.GenerationParams
 						// modelSettings takes priority over custom model params.
-						if ms := models.LoadModelSettingsFromConfig(); ms != nil {
+						if ms := models.LoadModelSettingsFrom(v); ms != nil {
 							perModelParams = ms[modelStr]
 						}
 						if perModelParams == nil && mi.Params != nil {
@@ -1349,6 +1378,10 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 
 			pb := skills.NewPromptBuilder(basePrompt)
 
+			// Capture the resolved base prompt so RefreshSystemPrompt can
+			// recompose later after runtime skill/context-file mutations.
+			capturedBasePrompt = basePrompt
+
 			// Inject AGENTS.md content as project context.
 			for _, cf := range contextFiles {
 				pb.WithSection("", fmt.Sprintf("Instructions from: %s\n\n%s", cf.Path, cf.Content))
@@ -1365,41 +1398,42 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 				time.Now().Format("Monday, January 2, 2006, 3:04:05 PM MST"), cwd,
 			))
 
-			viper.Set("system-prompt", pb.Build())
+			v.Set("system-prompt", pb.Build())
 		}
 
-		// Snapshot all viper-derived values now, while the lock is held.
-		// BuildProviderConfig is fast (pure reads), so we do it here.
+		// Snapshot all instance-derived values now.
+		// BuildProviderConfig is fast (pure reads).
 		var pcErr error
-		providerConfig, _, pcErr = kitsetup.BuildProviderConfig()
+		providerConfig, _, pcErr = kitsetup.BuildProviderConfig(v)
 		if pcErr != nil {
 			return fmt.Errorf("failed to build provider config: %w", pcErr)
 		}
 
 		// SDK last-resort max-tokens floor. When nothing — Options, env,
 		// config, nor a per-model default — supplied a value, we land on
-		// zero here (viper.GetInt returns 0 for unset keys). Apply the
-		// SDK default directly on the struct rather than via viper so
-		// viper.IsSet("max-tokens") stays false: downstream right-sizing
+		// zero here (GetInt returns 0 for unset keys). Apply the
+		// SDK default directly on the struct rather than via the store so
+		// IsSet("max-tokens") stays false: downstream right-sizing
 		// can still raise this toward the model's known output ceiling,
 		// and per-model modelSettings[...].maxTokens can still win.
 		if providerConfig.MaxTokens == 0 && opts.MaxTokens == 0 {
 			providerConfig.MaxTokens = sdkDefaultMaxTokens
 		}
-		modelString = viper.GetString("model")
-		debug = viper.GetBool("debug")
-		noExtensions = opts.NoExtensions || viper.GetBool("no-extensions")
-		maxSteps = viper.GetInt("max-steps")
-		streaming = viper.GetBool("stream")
+		modelString = v.GetString("model")
+		debug = v.GetBool("debug")
+		noExtensions = opts.NoExtensions || v.GetBool("no-extensions")
+		disableCoreTools = opts.DisableCoreTools || v.GetBool("no-core-tools")
+		maxSteps = v.GetInt("max-steps")
+		streaming = v.GetBool("stream")
 
 		return nil
 	}(); err != nil {
 		return nil, err
 	}
-	// ---- viperInitMu released — heavy I/O below runs concurrently ----
+	// ---- config snapshot complete — heavy I/O below ----
 
 	// Load MCP configuration. Use pre-loaded config if provided directly,
-	// via CLI options, or load from viper as a last resort.
+	// via CLI options, or load from the instance store as a last resort.
 	if opts.MCPConfig != nil {
 		mcpConfig = opts.MCPConfig
 	} else if opts.CLI != nil && opts.CLI.MCPConfig != nil {
@@ -1407,7 +1441,7 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 	}
 	if mcpConfig == nil {
 		var err error
-		mcpConfig, err = config.LoadAndValidateConfig()
+		mcpConfig, err = config.LoadAndValidateConfigFrom(v)
 		if err != nil {
 			return nil, fmt.Errorf("failed to load MCP config: %w", err)
 		}
@@ -1446,7 +1480,7 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 		MCPConfig:         mcpConfig,
 		Quiet:             opts.Quiet,
 		CoreTools:         opts.Tools,
-		DisableCoreTools:  opts.DisableCoreTools,
+		DisableCoreTools:  disableCoreTools,
 		ExtraTools:        opts.ExtraTools,
 		ToolWrapper:       hookToolWrapper(beforeToolCall, afterToolResult),
 		ProviderConfig:    providerConfig,
@@ -1463,6 +1497,7 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 			timeout:         opts.MCPTaskTimeout,
 			progress:        opts.MCPTaskProgress,
 		}.toToolsConfig(),
+		Viper: v,
 	}
 
 	// Set up OAuth handler for remote MCP servers. The SDK does not create
@@ -1532,8 +1567,10 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 		authHandler:           setupOpts.AuthHandler,
 		opts:                  opts,
 		mcpConfig:             mcpConfig,
+		v:                     v,
 		hasCustomSystemPrompt: hasCustomSystemPrompt,
 		systemPromptSource:    systemPromptSource,
+		basePrompt:            capturedBasePrompt,
 		beforeToolCall:        beforeToolCall,
 		afterToolResult:       afterToolResult,
 		beforeTurn:            beforeTurn,
@@ -1560,15 +1597,32 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 	return k, nil
 }
 
-// GetContextFiles returns the context files (e.g. AGENTS.md) loaded during
-// initialisation. Returns nil if no context files were found.
+// GetContextFiles returns the context files (e.g. AGENTS.md) currently active
+// on this Kit instance. The returned slice is a snapshot — mutating it does
+// not affect Kit state. Returns nil when no context files are loaded.
 func (m *Kit) GetContextFiles() []*ContextFile {
-	return m.contextFiles
+	m.runtimeMu.RLock()
+	defer m.runtimeMu.RUnlock()
+	if len(m.contextFiles) == 0 {
+		return nil
+	}
+	out := make([]*ContextFile, len(m.contextFiles))
+	copy(out, m.contextFiles)
+	return out
 }
 
-// GetSkills returns the skills loaded during initialisation.
+// GetSkills returns the skills currently active on this Kit instance. The
+// returned slice is a snapshot — mutating it does not affect Kit state.
+// Returns nil when no skills are loaded.
 func (m *Kit) GetSkills() []*Skill {
-	return m.skills
+	m.runtimeMu.RLock()
+	defer m.runtimeMu.RUnlock()
+	if len(m.skills) == 0 {
+		return nil
+	}
+	out := make([]*Skill, len(m.skills))
+	copy(out, m.skills)
+	return out
 }
 
 // ---------------------------------------------------------------------------
@@ -1613,12 +1667,14 @@ func (m *Kit) expandSkillCommand(prompt string) string {
 
 	// Find the skill by name.
 	var skillPath string
+	m.runtimeMu.RLock()
 	for _, s := range m.skills {
 		if s.Name == name {
 			skillPath = s.Path
 			break
 		}
 	}
+	m.runtimeMu.RUnlock()
 	if skillPath == "" {
 		return prompt
 	}
@@ -1791,6 +1847,50 @@ type SubagentResult struct {
 	Elapsed time.Duration
 }
 
+// inheritProviderConfig copies the parent's effective provider/runtime
+// configuration from its isolated config store onto child Options. Used by
+// Kit.Subagent so the child — which owns a separate store and re-loads only
+// .kit.yml / KIT_* on its own — still observes provider credentials, the
+// thinking level, and sampler/token overrides the parent acquired via
+// programmatic Options or runtime setters (e.g. SetThinkingLevel).
+//
+// max-tokens and the sampling parameters are only propagated when the parent
+// explicitly set them (IsSet), preserving the tri-state precedence so per-model
+// defaults still apply on the child when the parent left them unset. A nil
+// child or store is a no-op.
+func inheritProviderConfig(child *Options, v *viper.Viper) {
+	if child == nil || v == nil {
+		return
+	}
+	child.ProviderAPIKey = v.GetString("provider-api-key")
+	child.ProviderURL = v.GetString("provider-url")
+	child.TLSSkipVerify = v.GetBool("tls-skip-verify")
+	child.ThinkingLevel = v.GetString("thinking-level")
+	if v.IsSet("max-tokens") {
+		child.MaxTokens = v.GetInt("max-tokens")
+	}
+	if v.IsSet("temperature") {
+		t := float32(v.GetFloat64("temperature"))
+		child.Temperature = &t
+	}
+	if v.IsSet("top-p") {
+		p := float32(v.GetFloat64("top-p"))
+		child.TopP = &p
+	}
+	if v.IsSet("top-k") {
+		k := int32(v.GetInt("top-k"))
+		child.TopK = &k
+	}
+	if v.IsSet("frequency-penalty") {
+		fp := float32(v.GetFloat64("frequency-penalty"))
+		child.FrequencyPenalty = &fp
+	}
+	if v.IsSet("presence-penalty") {
+		pp := float32(v.GetFloat64("presence-penalty"))
+		child.PresencePenalty = &pp
+	}
+}
+
 // Subagent spawns an in-process child Kit instance to perform a task. The
 // child gets its own session, event bus, and agent loop but shares the
 // parent's config (API keys, provider settings) and defaults to the parent's
@@ -1860,22 +1960,28 @@ func (m *Kit) Subagent(ctx context.Context, cfg SubagentConfig) (*SubagentResult
 	}
 
 	// Create child Kit instance. Pass the parent's loaded MCP config to
-	// avoid re-reading viper (which races with concurrent subagent spawns).
-	// Streaming must be explicitly enabled — Options.Streaming defaults to
-	// false, and New() unconditionally writes viper.Set("stream", opts.Streaming).
-	// Without this, the subagent would (a) pollute viper global state for
-	// other concurrent callers and (b) potentially hit provider-level
-	// differences (e.g. Anthropic non-streaming timeouts with extended
-	// thinking).
+	// avoid re-loading and re-validating config for the child.
+	// Streaming is enabled explicitly — without it, non-streaming can hit
+	// provider-level differences (e.g. Anthropic non-streaming timeouts with
+	// extended thinking). The child gets its own config store, so this does not
+	// affect any other concurrent caller.
+	streamOn := true
 	childOpts := &Options{
 		Model:        model,
 		SystemPrompt: systemPrompt,
 		Tools:        tools,
 		NoSession:    cfg.NoSession,
 		Quiet:        true,
-		Streaming:    true,
+		Streaming:    &streamOn,
 		MCPConfig:    m.mcpConfig,
 	}
+
+	// Inherit the parent's effective provider/runtime configuration. Since #40
+	// each Kit owns an isolated config store, so the child's New() only re-loads
+	// .kit.yml / KIT_* on its own — values the parent picked up from
+	// programmatic Options or runtime setters (e.g. SetThinkingLevel) would
+	// otherwise be lost.
+	inheritProviderConfig(childOpts, m.v)
 	// Propagate the parent's MCP task configuration so a child subagent
 	// invoking long-running MCP tools observes the same per-server modes,
 	// timeouts, and progress callback as the parent. Without this, child
@@ -2084,7 +2190,7 @@ func (m *Kit) generate(ctx context.Context, messages []fantasy.Message) (*agent.
 			}
 		},
 		OnStepUsage: func(inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens int64) {
-			if viper.GetBool("debug") {
+			if m.v.GetBool("debug") {
 				log.Printf("DEBUG Kit.generate emitting StepUsageEvent: input=%d output=%d cacheRead=%d cacheCreate=%d",
 					inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens,
 				)
@@ -2126,7 +2232,7 @@ func (m *Kit) generate(ctx context.Context, messages []fantasy.Message) (*agent.
 			})
 		},
 
-		// New callbacks for previously unwired Fantasy lifecycle events.
+		// New callbacks for previously unwired agent lifecycle events.
 		OnStepStart: func(stepNumber int) {
 			m.events.emit(StepStartEvent{StepNumber: stepNumber})
 		},
@@ -2580,7 +2686,7 @@ func (m *Kit) IsReasoningModel() bool {
 
 // GetThinkingLevel returns the current thinking level.
 func (m *Kit) GetThinkingLevel() string {
-	return viper.GetString("thinking-level")
+	return m.v.GetString("thinking-level")
 }
 
 // SetThinkingLevel changes the thinking level and recreates the agent with
@@ -2589,7 +2695,7 @@ func (m *Kit) GetThinkingLevel() string {
 // With message-level caching, both thinking and caching work together.
 // Caching reduces costs by 60-90% for repeated context.
 func (m *Kit) SetThinkingLevel(ctx context.Context, level string) error {
-	viper.Set("thinking-level", level)
+	m.v.Set("thinking-level", level)
 	// Recreate agent with new thinking config by re-running SetModel
 	// with the same model string. SetModel rebuilds the provider and
 	// passes the updated viper config (including thinking-level).

pkg/kit/kit_test.go

@@ -86,8 +86,8 @@ func TestNewWithGenerationOptions(t *testing.T) {
 		if got := host.MaxTokens(); got != want {
 			t.Errorf("Options.MaxTokens=%d did not propagate; Kit.MaxTokens()=%d", want, got)
 		}
-		if !viper.IsSet("max-tokens") {
-			t.Error("viper.IsSet(\"max-tokens\") should be true after MaxTokens override")
+		if !host.ConfigValueIsSetForTest("max-tokens") {
+			t.Error("max-tokens should be marked explicitly set on the instance store after MaxTokens override")
 		}
 	})
 
@@ -129,11 +129,11 @@ func TestNewWithGenerationOptions(t *testing.T) {
 		}
 		defer func() { _ = host.Close() }()
 
-		if !viper.IsSet("temperature") {
-			t.Fatal("viper.IsSet(\"temperature\") should be true after Temperature override")
+		if !host.ConfigValueIsSetForTest("temperature") {
+			t.Fatal("temperature should be marked explicitly set on the instance store after Temperature override")
 		}
-		if got := float32(viper.GetFloat64("temperature")); got != want {
-			t.Errorf("Options.Temperature=%v did not propagate; viper=%v", want, got)
+		if got := float32(host.ConfigFloatForTest("temperature")); got != want {
+			t.Errorf("Options.Temperature=%v did not propagate; instance store=%v", want, got)
 		}
 	})
 }
@@ -185,8 +185,8 @@ func TestNewPreservesIsSetSemantics(t *testing.T) {
 	// from SDK-side SetDefault/Set calls — which is exactly what this
 	// test is guarding against.
 	for _, k := range checkKeys {
-		if viper.IsSet(k) {
-			t.Errorf("viper.IsSet(%q) == true when no Options field set it "+
+		if host.ConfigValueIsSetForTest(k) {
+			t.Errorf("instance store reports %q explicitly set when no Options field set it "+
 				"(SDK defaults must not corrupt IsSet semantics)", k)
 		}
 	}
@@ -217,14 +217,14 @@ func TestNewWithProviderOptions(t *testing.T) {
 		}
 		defer func() { _ = host.Close() }()
 
-		if got := viper.GetString("provider-api-key"); got != apiKey {
-			t.Errorf("Options.ProviderAPIKey did not propagate to viper; got %q (len=%d)", got, len(got))
+		if got := host.ConfigStringForTest("provider-api-key"); got != apiKey {
+			t.Errorf("Options.ProviderAPIKey did not propagate to the instance store; got %q (len=%d)", got, len(got))
 		}
 	})
 
-	// Override precedence: even when viper already holds a different
-	// provider-api-key value (as it would if a config file or earlier
-	// Set() call populated one), Options.ProviderAPIKey must win.
+	// Override precedence: even when the process-global store already holds a
+	// different provider-api-key value, Options.ProviderAPIKey must win on the
+	// Kit's isolated store.
 	t.Run("Options override beats pre-existing viper state", func(t *testing.T) {
 		defer resetViper()
 
@@ -242,15 +242,16 @@ func TestNewWithProviderOptions(t *testing.T) {
 			ProviderAPIKey:   want,
 		})
 		// Creation may still fail if the model registry is strict, but
-		// we only care that the override reached viper before any
-		// provider handshake happened.
-		if host != nil {
-			defer func() { _ = host.Close() }()
+		// we only care that the override reached the instance store before
+		// any provider handshake happened.
+		if host == nil {
+			t.Fatalf("expected a Kit instance to inspect; got nil (err=%v)", err)
 		}
+		defer func() { _ = host.Close() }()
 		_ = err
 
-		if got := viper.GetString("provider-api-key"); got != want {
-			t.Errorf("Options.ProviderAPIKey did not override pre-existing viper value; got %q, want %q", got, want)
+		if got := host.ConfigStringForTest("provider-api-key"); got != want {
+			t.Errorf("Options.ProviderAPIKey did not override pre-existing value on the instance store; got %q, want %q", got, want)
 		}
 	})
 
@@ -270,7 +271,7 @@ func TestNewWithProviderOptions(t *testing.T) {
 		}
 		defer func() { _ = host.Close() }()
 
-		if got := viper.GetString("provider-url"); got != want {
+		if got := host.ConfigStringForTest("provider-url"); got != want {
 			t.Errorf("Options.ProviderURL did not propagate; got %q, want %q", got, want)
 		}
 	})
@@ -353,9 +354,9 @@ func TestNewSystemPromptFilePath(t *testing.T) {
 		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")
+	// The composed system prompt is written back to the instance store after
+	// PromptBuilder runs. It must contain the file's contents, not the file path.
+	composed := host.ConfigStringForTest("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)
 	}
@@ -392,7 +393,7 @@ func TestNewSystemPromptInline(t *testing.T) {
 	if got := host.GetSystemPromptSource(); got != inline {
 		t.Errorf("GetSystemPromptSource() = %q; want %q", got, inline)
 	}
-	if composed := viper.GetString("system-prompt"); !strings.Contains(composed, inline) {
+	if composed := host.ConfigStringForTest("system-prompt"); !strings.Contains(composed, inline) {
 		t.Errorf("composed system-prompt missing inline content; got %q", composed)
 	}
 }

pkg/kit/mcp_tasks_test.go

@@ -4,6 +4,8 @@ import (
 	"testing"
 	"time"
 
+	"github.com/spf13/viper"
+
 	"github.com/mark3labs/kit/internal/tools"
 )
 
@@ -163,3 +165,82 @@ func TestSubagentPropagatesMCPTaskOptions(t *testing.T) {
 	inheritMCPTaskOptions(&Options{}, nil)
 	inheritMCPTaskOptions(nil, parent)
 }
+
+// TestInheritProviderConfig verifies that Kit.Subagent's provider/runtime
+// config inheritance copies the parent's effective settings onto child
+// Options, and that the tri-state (IsSet) keys are only propagated when the
+// parent explicitly set them. Regression test for config loss after the
+// per-instance viper store isolation (#40).
+func TestInheritProviderConfig(t *testing.T) {
+	t.Run("explicit values propagate", func(t *testing.T) {
+		v := viper.New()
+		v.Set("provider-api-key", "sk-parent")
+		v.Set("provider-url", "https://proxy.internal/v1")
+		v.Set("tls-skip-verify", true)
+		v.Set("thinking-level", "high")
+		v.Set("max-tokens", 4321)
+		v.Set("temperature", 0.25)
+		v.Set("top-p", 0.9)
+		v.Set("top-k", 40)
+		v.Set("frequency-penalty", 0.1)
+		v.Set("presence-penalty", 0.2)
+
+		child := &Options{}
+		inheritProviderConfig(child, v)
+
+		if child.ProviderAPIKey != "sk-parent" {
+			t.Errorf("ProviderAPIKey = %q, want sk-parent", child.ProviderAPIKey)
+		}
+		if child.ProviderURL != "https://proxy.internal/v1" {
+			t.Errorf("ProviderURL = %q", child.ProviderURL)
+		}
+		if !child.TLSSkipVerify {
+			t.Error("TLSSkipVerify not propagated")
+		}
+		if child.ThinkingLevel != "high" {
+			t.Errorf("ThinkingLevel = %q, want high", child.ThinkingLevel)
+		}
+		if child.MaxTokens != 4321 {
+			t.Errorf("MaxTokens = %d, want 4321", child.MaxTokens)
+		}
+		if child.Temperature == nil || *child.Temperature != 0.25 {
+			t.Errorf("Temperature = %v, want 0.25", child.Temperature)
+		}
+		if child.TopP == nil || *child.TopP != 0.9 {
+			t.Errorf("TopP = %v, want 0.9", child.TopP)
+		}
+		if child.TopK == nil || *child.TopK != 40 {
+			t.Errorf("TopK = %v, want 40", child.TopK)
+		}
+		if child.FrequencyPenalty == nil || *child.FrequencyPenalty != 0.1 {
+			t.Errorf("FrequencyPenalty = %v, want 0.1", child.FrequencyPenalty)
+		}
+		if child.PresencePenalty == nil || *child.PresencePenalty != 0.2 {
+			t.Errorf("PresencePenalty = %v, want 0.2", child.PresencePenalty)
+		}
+	})
+
+	t.Run("unset tri-state keys stay unset", func(t *testing.T) {
+		// A store with no sampler / max-tokens keys must leave the child's
+		// pointers nil and MaxTokens zero so per-model defaults still apply.
+		v := viper.New()
+		child := &Options{}
+		inheritProviderConfig(child, v)
+
+		if child.MaxTokens != 0 {
+			t.Errorf("MaxTokens = %d, want 0 (unset)", child.MaxTokens)
+		}
+		if child.Temperature != nil || child.TopP != nil || child.TopK != nil ||
+			child.FrequencyPenalty != nil || child.PresencePenalty != nil {
+			t.Error("sampler pointers must stay nil when the parent did not set them")
+		}
+		if child.ThinkingLevel != "" {
+			t.Errorf("ThinkingLevel = %q, want empty", child.ThinkingLevel)
+		}
+	})
+
+	t.Run("nil child or store is a no-op", func(t *testing.T) {
+		inheritProviderConfig(nil, viper.New())
+		inheritProviderConfig(&Options{}, nil)
+	})
+}

pkg/kit/options.go

@@ -0,0 +1,88 @@
+package kit
+
+import "context"
+
+// Option configures a [Kit] created via [NewAgent]. Options are applied in
+// order to an [Options] value, so later options override earlier ones. The
+// type is a plain func(*Options), so callers can define their own options
+// without depending on any internal type.
+type Option func(*Options)
+
+// NewAgent creates a Kit using an ergonomic functional-options API. It is a
+// thin, additive front door over [New]: the supplied options are applied to a
+// fresh [Options] value which is then passed to [New]. For advanced
+// configuration not covered by the With* helpers (MCPConfig,
+// InProcessMCPServers, session backends, MCP task tuning, etc.) construct an
+// [Options] explicitly and call [New].
+//
+// Streaming defaults to enabled. Pass WithStreaming(false) to disable it.
+//
+// Example:
+//
+//	k, err := kit.NewAgent(ctx,
+//	    kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+//	    kit.WithSystemPrompt("You are a helpful assistant."),
+//	    kit.WithMaxTokens(8192),
+//	    kit.Ephemeral(),
+//	)
+func NewAgent(ctx context.Context, opts ...Option) (*Kit, error) {
+	// Streaming defaults to true for the ergonomic constructor — this is the
+	// natural expectation for interactive agents. WithStreaming(false) overrides it.
+	streamOn := true
+	o := &Options{Streaming: &streamOn}
+	for _, fn := range opts {
+		fn(o)
+	}
+	return New(ctx, o)
+}
+
+// WithModel sets the model in "provider/model" format
+// (e.g. "anthropic/claude-sonnet-4-5-20250929").
+func WithModel(m string) Option { return func(o *Options) { o.Model = m } }
+
+// WithSystemPrompt sets the system prompt. The value may be inline text or a
+// path to a file whose contents are loaded as the prompt.
+func WithSystemPrompt(p string) Option { return func(o *Options) { o.SystemPrompt = p } }
+
+// WithStreaming enables or disables streaming responses. [NewAgent] enables
+// streaming by default, so pass WithStreaming(false) to opt out.
+func WithStreaming(b bool) Option {
+	return func(o *Options) { o.Streaming = &b }
+}
+
+// WithMaxTokens sets the maximum output tokens per LLM response. A value of 0
+// lets the precedence chain (env → config → per-model → SDK floor) resolve a
+// value; a non-zero value pins it and suppresses automatic right-sizing.
+func WithMaxTokens(n int) Option { return func(o *Options) { o.MaxTokens = n } }
+
+// WithThinkingLevel sets the reasoning effort for models that support extended
+// thinking. Valid values: "off", "none", "minimal", "low", "medium", "high".
+// An empty string lets the precedence chain resolve a level.
+func WithThinkingLevel(level string) Option { return func(o *Options) { o.ThinkingLevel = level } }
+
+// WithTools sets the agent's tool set, replacing the default core tools. When
+// no tools are provided the default set is used.
+func WithTools(t ...Tool) Option { return func(o *Options) { o.Tools = t } }
+
+// WithExtraTools adds tools alongside the core/MCP/extension tools rather than
+// replacing them.
+func WithExtraTools(t ...Tool) Option { return func(o *Options) { o.ExtraTools = t } }
+
+// WithProviderAPIKey overrides the API key used to authenticate with the model
+// provider.
+func WithProviderAPIKey(key string) Option { return func(o *Options) { o.ProviderAPIKey = key } }
+
+// WithProviderURL overrides the provider endpoint URL. Useful for
+// OpenAI-compatible proxies (LiteLLM, vLLM, Azure OpenAI, etc.).
+func WithProviderURL(url string) Option { return func(o *Options) { o.ProviderURL = url } }
+
+// WithConfigFile sets an explicit config file path, overriding the default
+// .kit.yml search.
+func WithConfigFile(path string) Option { return func(o *Options) { o.ConfigFile = path } }
+
+// WithDebug enables SDK debug logging.
+func WithDebug() Option { return func(o *Options) { o.Debug = true } }
+
+// Ephemeral configures an in-memory session with no persistence (equivalent to
+// Options.NoSession = true).
+func Ephemeral() Option { return func(o *Options) { o.NoSession = true } }

pkg/kit/runtime_skills_context_test.go

@@ -0,0 +1,342 @@
+package kit
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/mark3labs/kit/internal/agent"
+	"github.com/mark3labs/kit/internal/skills"
+)
+
+// TestAddSkill_AddsAndDeduplicates verifies that AddSkill registers new skills
+// and that re-adding a skill with the same Name replaces the existing entry
+// rather than appending a duplicate. agent is nil in these tests; the method
+// must still mutate the in-memory state and tolerate the absent agent.
+func TestAddSkill_AddsAndDeduplicates(t *testing.T) {
+	k := &Kit{basePrompt: "base"}
+
+	if err := k.AddSkill(&skills.Skill{Name: "alpha", Content: "first"}); err != nil {
+		t.Fatalf("AddSkill alpha: %v", err)
+	}
+	if err := k.AddSkill(&skills.Skill{Name: "beta", Content: "second"}); err != nil {
+		t.Fatalf("AddSkill beta: %v", err)
+	}
+	got := k.GetSkills()
+	if len(got) != 2 {
+		t.Fatalf("expected 2 skills, got %d", len(got))
+	}
+
+	// Re-adding alpha with new content must replace, not duplicate.
+	if err := k.AddSkill(&skills.Skill{Name: "alpha", Content: "replaced"}); err != nil {
+		t.Fatalf("AddSkill alpha replace: %v", err)
+	}
+	got = k.GetSkills()
+	if len(got) != 2 {
+		t.Fatalf("expected 2 skills after replace, got %d", len(got))
+	}
+	for _, s := range got {
+		if s.Name == "alpha" && s.Content != "replaced" {
+			t.Errorf("alpha content = %q; want %q", s.Content, "replaced")
+		}
+	}
+}
+
+// TestAddSkill_Validation rejects nil skills and unnamed skills with errors
+// instead of corrupting state.
+func TestAddSkill_Validation(t *testing.T) {
+	k := &Kit{}
+	if err := k.AddSkill(nil); err == nil {
+		t.Error("expected error for nil skill")
+	}
+	if err := k.AddSkill(&skills.Skill{Content: "x"}); err == nil {
+		t.Error("expected error for unnamed skill")
+	}
+	if got := k.GetSkills(); got != nil {
+		t.Errorf("skills list mutated after invalid AddSkill calls: %#v", got)
+	}
+}
+
+// TestRemoveSkill verifies removal and the false return for misses.
+func TestRemoveSkill(t *testing.T) {
+	k := &Kit{}
+	_ = k.AddSkill(&skills.Skill{Name: "alpha"})
+	_ = k.AddSkill(&skills.Skill{Name: "beta"})
+
+	if removed := k.RemoveSkill("missing"); removed {
+		t.Error("RemoveSkill(missing) = true; want false")
+	}
+	if removed := k.RemoveSkill("alpha"); !removed {
+		t.Error("RemoveSkill(alpha) = false; want true")
+	}
+	got := k.GetSkills()
+	if len(got) != 1 || got[0].Name != "beta" {
+		t.Errorf("remaining skills = %#v; want [beta]", got)
+	}
+}
+
+// TestSetSkills replaces the entire set and validates input.
+func TestSetSkills(t *testing.T) {
+	k := &Kit{}
+	_ = k.AddSkill(&skills.Skill{Name: "alpha"})
+
+	err := k.SetSkills([]*skills.Skill{
+		{Name: "one"},
+		{Name: "two"},
+		{Name: "three"},
+	})
+	if err != nil {
+		t.Fatalf("SetSkills: %v", err)
+	}
+	if got := k.GetSkills(); len(got) != 3 {
+		t.Errorf("expected 3 skills, got %d", len(got))
+	}
+
+	// Invalid entry rejects the whole batch.
+	bad := []*skills.Skill{{Name: "ok"}, nil}
+	if err := k.SetSkills(bad); err == nil {
+		t.Error("expected error when batch contains nil")
+	}
+	// State unchanged after rejected batch.
+	if got := k.GetSkills(); len(got) != 3 {
+		t.Errorf("skills mutated by rejected SetSkills batch: len=%d", len(got))
+	}
+
+	// Empty slice clears.
+	if err := k.SetSkills(nil); err != nil {
+		t.Fatalf("SetSkills(nil): %v", err)
+	}
+	if got := k.GetSkills(); got != nil {
+		t.Errorf("expected nil skills after clear; got %#v", got)
+	}
+}
+
+// TestLoadAndAddSkill round-trips a skill file from disk.
+func TestLoadAndAddSkill(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "demo.md")
+	body := "---\nname: demo\ndescription: demo skill\n---\nhello world"
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatalf("write skill file: %v", err)
+	}
+
+	k := &Kit{}
+	s, err := k.LoadAndAddSkill(path)
+	if err != nil {
+		t.Fatalf("LoadAndAddSkill: %v", err)
+	}
+	if s.Name != "demo" {
+		t.Errorf("loaded skill Name = %q; want demo", s.Name)
+	}
+	if got := k.GetSkills(); len(got) != 1 {
+		t.Errorf("expected 1 skill registered, got %d", len(got))
+	}
+}
+
+// TestAddContextFile_DeduplicatesByPath confirms identical paths replace
+// rather than duplicate.
+func TestAddContextFile_DeduplicatesByPath(t *testing.T) {
+	k := &Kit{}
+	if err := k.AddContextFile(&ContextFile{Path: "/a/AGENTS.md", Content: "v1"}); err != nil {
+		t.Fatalf("AddContextFile: %v", err)
+	}
+	if err := k.AddContextFile(&ContextFile{Path: "/b/AGENTS.md", Content: "vB"}); err != nil {
+		t.Fatalf("AddContextFile: %v", err)
+	}
+	if err := k.AddContextFile(&ContextFile{Path: "/a/AGENTS.md", Content: "v2"}); err != nil {
+		t.Fatalf("AddContextFile replace: %v", err)
+	}
+
+	got := k.GetContextFiles()
+	if len(got) != 2 {
+		t.Fatalf("expected 2 context files, got %d", len(got))
+	}
+	for _, cf := range got {
+		if cf.Path == "/a/AGENTS.md" && cf.Content != "v2" {
+			t.Errorf("/a/AGENTS.md content = %q; want v2", cf.Content)
+		}
+	}
+}
+
+// TestAddContextFile_Validation rejects nil and unpathed entries.
+func TestAddContextFile_Validation(t *testing.T) {
+	k := &Kit{}
+	if err := k.AddContextFile(nil); err == nil {
+		t.Error("expected error for nil context file")
+	}
+	if err := k.AddContextFile(&ContextFile{Content: "x"}); err == nil {
+		t.Error("expected error for empty path")
+	}
+}
+
+// TestRemoveContextFile_Behavior verifies remove returns true on hit and
+// false on miss without mutating state on a miss.
+func TestRemoveContextFile_Behavior(t *testing.T) {
+	k := &Kit{}
+	_ = k.AddContextFile(&ContextFile{Path: "/a", Content: "x"})
+	_ = k.AddContextFile(&ContextFile{Path: "/b", Content: "y"})
+
+	if removed := k.RemoveContextFile("/missing"); removed {
+		t.Error("RemoveContextFile(missing) = true; want false")
+	}
+	if removed := k.RemoveContextFile("/a"); !removed {
+		t.Error("RemoveContextFile(/a) = false; want true")
+	}
+	got := k.GetContextFiles()
+	if len(got) != 1 || got[0].Path != "/b" {
+		t.Errorf("remaining = %#v; want [/b]", got)
+	}
+}
+
+// TestSetContextFiles replaces and validates batch input.
+func TestSetContextFiles(t *testing.T) {
+	k := &Kit{}
+	_ = k.AddContextFile(&ContextFile{Path: "/seed", Content: "old"})
+
+	err := k.SetContextFiles([]*ContextFile{
+		{Path: "/x", Content: "x"},
+		{Path: "/y", Content: "y"},
+	})
+	if err != nil {
+		t.Fatalf("SetContextFiles: %v", err)
+	}
+	if got := k.GetContextFiles(); len(got) != 2 {
+		t.Errorf("expected 2 context files, got %d", len(got))
+	}
+
+	bad := []*ContextFile{{Path: "/ok"}, {Path: ""}}
+	if err := k.SetContextFiles(bad); err == nil {
+		t.Error("expected error for empty path in batch")
+	}
+	if got := k.GetContextFiles(); len(got) != 2 {
+		t.Errorf("state mutated by rejected batch: len=%d", len(got))
+	}
+
+	if err := k.SetContextFiles(nil); err != nil {
+		t.Fatalf("SetContextFiles(nil): %v", err)
+	}
+	if got := k.GetContextFiles(); got != nil {
+		t.Errorf("expected nil after clear; got %#v", got)
+	}
+}
+
+// TestLoadAndAddContextFile reads from disk and registers the context file.
+func TestLoadAndAddContextFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "AGENTS.md")
+	const content = "# Agent rules\nuse the new lint config"
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	k := &Kit{}
+	cf, err := k.LoadAndAddContextFile(path)
+	if err != nil {
+		t.Fatalf("LoadAndAddContextFile: %v", err)
+	}
+	if !strings.HasSuffix(cf.Path, "AGENTS.md") {
+		t.Errorf("Path = %q; want suffix AGENTS.md", cf.Path)
+	}
+	if !strings.Contains(cf.Content, "use the new lint config") {
+		t.Errorf("Content missing expected body: %q", cf.Content)
+	}
+	got := k.GetContextFiles()
+	if len(got) != 1 {
+		t.Fatalf("expected 1 context file, got %d", len(got))
+	}
+}
+
+// TestAddContextFileContent registers an in-memory context blob.
+func TestAddContextFileContent(t *testing.T) {
+	k := &Kit{}
+	cf, err := k.AddContextFileContent("session://user-123/AGENTS.md", "always greet in French")
+	if err != nil {
+		t.Fatalf("AddContextFileContent: %v", err)
+	}
+	if cf.Path != "session://user-123/AGENTS.md" {
+		t.Errorf("Path = %q", cf.Path)
+	}
+	if cf.Content != "always greet in French" {
+		t.Errorf("Content = %q", cf.Content)
+	}
+}
+
+// TestComposeSystemPrompt_IncludesSkillsAndContext verifies that runtime
+// mutations actually flow into the composed system prompt that the agent
+// would receive.
+func TestComposeSystemPrompt_IncludesSkillsAndContext(t *testing.T) {
+	k := &Kit{basePrompt: "BASE-PROMPT-MARKER"}
+
+	if err := k.AddContextFile(&ContextFile{
+		Path:    "/proj/AGENTS.md",
+		Content: "CTX-MARKER-OK",
+	}); err != nil {
+		t.Fatalf("AddContextFile: %v", err)
+	}
+	if err := k.AddSkill(&skills.Skill{
+		Name:        "greeter",
+		Description: "SKILL-DESC-MARKER",
+		Content:     "do greetings",
+		Path:        "/skills/greeter.md",
+	}); err != nil {
+		t.Fatalf("AddSkill: %v", err)
+	}
+
+	composed := k.composeSystemPrompt(k.basePrompt)
+	for _, want := range []string{
+		"BASE-PROMPT-MARKER",
+		"CTX-MARKER-OK",
+		"/proj/AGENTS.md",
+		"greeter",
+		"SKILL-DESC-MARKER",
+	} {
+		if !strings.Contains(composed, want) {
+			t.Errorf("composed prompt missing %q\n--- composed ---\n%s", want, composed)
+		}
+	}
+
+	// Removing the skill should remove its marker from the next composition.
+	k.RemoveSkill("greeter")
+	composed = k.composeSystemPrompt(k.basePrompt)
+	if strings.Contains(composed, "SKILL-DESC-MARKER") {
+		t.Errorf("composed prompt still contains removed skill description:\n%s", composed)
+	}
+}
+
+// TestRuntimeMutations_AreThreadSafe stresses the mutation API from multiple
+// goroutines to surface data races under `go test -race`.
+func TestRuntimeMutations_AreThreadSafe(t *testing.T) {
+	// Use a non-nil agent so applyComposedSystemPrompt actually invokes
+	// agent.SetSystemPrompt (a no-op agent is fine — we only need the
+	// systemPrompt mutation + fantasy rebuild path to run concurrently so
+	// -race can observe any unsynchronized writes).
+	k := &Kit{basePrompt: "base", agent: &agent.Agent{}}
+	var wg sync.WaitGroup
+	const goroutines = 8
+	const iterations = 50
+
+	for g := range goroutines {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for range iterations {
+				_ = k.AddSkill(&skills.Skill{
+					Name:    "skill",
+					Content: "content",
+				})
+				_ = k.AddContextFile(&ContextFile{
+					Path:    "/shared/AGENTS.md",
+					Content: "shared",
+				})
+				_ = k.GetSkills()
+				_ = k.GetContextFiles()
+				_ = k.composeSystemPrompt("base")
+				k.RemoveSkill("skill")
+				k.RemoveContextFile("/shared/AGENTS.md")
+			}
+		}(g)
+	}
+	wg.Wait()
+}

pkg/kit/skills.go

@@ -139,13 +139,150 @@ func (m *Kit) ClearSkillCache() {
 }
 
 // ReloadSkills re-discovers skills from disk, replacing the current set.
-// This is called by file watchers when skill files change.
+// This is called by file watchers when skill files change. The system prompt
+// is recomposed and applied to the running agent so subsequent turns see the
+// new skill set.
 func (m *Kit) ReloadSkills() error {
 	newSkills, err := loadSkills(m.opts)
 	if err != nil {
 		return fmt.Errorf("reloading skills: %w", err)
 	}
+	m.runtimeMu.Lock()
 	m.skills = newSkills
+	m.runtimeMu.Unlock()
 	m.ClearSkillCache()
+	m.applyComposedSystemPrompt()
 	return nil
 }
+
+// ---------------------------------------------------------------------------
+// Runtime skill management (Issue #36)
+// ---------------------------------------------------------------------------
+//
+// The methods below let SDK consumers (chatbot hosts, multi-tenant agents)
+// mutate the active skill set after Kit construction. Each mutation recomposes
+// the system prompt and applies it to the underlying agent so the LLM sees
+// the new skill metadata on its next turn.
+
+// AddSkill registers a single skill on this Kit instance. The skill object
+// can be built programmatically (no file on disk required) — only Name and
+// Content are mandatory. If a skill with the same Name is already loaded the
+// new skill replaces it. Returns an error when skill is nil or has an empty
+// name.
+//
+// After mutation the system prompt is recomposed and applied to the running
+// agent so the next turn sees the updated skill metadata. AddSkill is safe to
+// call from any goroutine.
+func (m *Kit) AddSkill(skill *Skill) error {
+	if skill == nil {
+		return fmt.Errorf("AddSkill: skill is nil")
+	}
+	if skill.Name == "" {
+		return fmt.Errorf("AddSkill: skill name is required")
+	}
+
+	m.runtimeMu.Lock()
+	replaced := false
+	for i, s := range m.skills {
+		if s.Name == skill.Name {
+			m.skills[i] = skill
+			replaced = true
+			break
+		}
+	}
+	if !replaced {
+		m.skills = append(m.skills, skill)
+	}
+	m.runtimeMu.Unlock()
+
+	m.ClearSkillCache()
+	m.applyComposedSystemPrompt()
+	return nil
+}
+
+// LoadAndAddSkill loads a skill from a filesystem path (single .md/.txt file)
+// and adds it via [Kit.AddSkill]. Returns the loaded skill on success.
+func (m *Kit) LoadAndAddSkill(path string) (*Skill, error) {
+	s, err := skills.LoadSkill(path)
+	if err != nil {
+		return nil, fmt.Errorf("LoadAndAddSkill: %w", err)
+	}
+	if err := m.AddSkill(s); err != nil {
+		return nil, err
+	}
+	return s, nil
+}
+
+// RemoveSkill removes the named skill from this Kit instance and recomposes
+// the system prompt. Returns true when a skill with that name was found and
+// removed, false otherwise.
+func (m *Kit) RemoveSkill(name string) bool {
+	m.runtimeMu.Lock()
+	found := false
+	for i, s := range m.skills {
+		if s.Name == name {
+			m.skills = append(m.skills[:i], m.skills[i+1:]...)
+			found = true
+			break
+		}
+	}
+	m.runtimeMu.Unlock()
+
+	if !found {
+		return false
+	}
+	m.ClearSkillCache()
+	m.applyComposedSystemPrompt()
+	return true
+}
+
+// SetSkills replaces the active skill set with the provided slice. Pass nil
+// or an empty slice to remove all skills. The system prompt is recomposed and
+// applied. Skills with empty names are rejected and no mutation is performed.
+func (m *Kit) SetSkills(skillList []*Skill) error {
+	// Validate first so a bad input doesn't partially mutate state.
+	for i, s := range skillList {
+		if s == nil {
+			return fmt.Errorf("SetSkills: skill at index %d is nil", i)
+		}
+		if s.Name == "" {
+			return fmt.Errorf("SetSkills: skill at index %d has empty name", i)
+		}
+	}
+
+	copied := make([]*Skill, len(skillList))
+	copy(copied, skillList)
+
+	m.runtimeMu.Lock()
+	m.skills = copied
+	m.runtimeMu.Unlock()
+
+	m.ClearSkillCache()
+	m.applyComposedSystemPrompt()
+	return nil
+}
+
+// applyComposedSystemPrompt recomposes the system prompt from the captured
+// base prompt + current contextFiles + current skills + date/cwd, and pushes
+// the result onto the underlying agent. No-op when the agent is unset (i.e.
+// during construction).
+func (m *Kit) applyComposedSystemPrompt() {
+	if m.agent == nil {
+		return
+	}
+	m.runtimeMu.RLock()
+	base := m.basePrompt
+	m.runtimeMu.RUnlock()
+	composed := m.composeSystemPrompt(base)
+	m.agent.SetSystemPrompt(composed)
+}
+
+// RefreshSystemPrompt manually recomposes the system prompt from the current
+// skills and context files and applies it to the agent. Call this after a
+// batch of low-level mutations or to force a re-render of the date/cwd
+// section. Most callers don't need to invoke this directly because
+// AddSkill, RemoveSkill, SetSkills, AddContextFile, RemoveContextFile, and
+// SetContextFiles all refresh automatically.
+func (m *Kit) RefreshSystemPrompt() {
+	m.applyComposedSystemPrompt()
+}

pkg/kit/viper_isolation_test.go

@@ -0,0 +1,232 @@
+package kit_test
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/mark3labs/kit/pkg/kit"
+)
+
+// TestOptionFunctionsPlumbing verifies that the functional options apply their
+// values to the underlying Options struct. This does not create a provider, so
+// it runs without API keys.
+func TestOptionFunctionsPlumbing(t *testing.T) {
+	o := &kit.Options{}
+	opts := []kit.Option{
+		kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+		kit.WithSystemPrompt("be terse"),
+		kit.WithMaxTokens(4321),
+		kit.WithThinkingLevel("high"),
+		kit.WithProviderAPIKey("sk-test"),
+		kit.WithProviderURL("https://example.test/v1"),
+		kit.WithConfigFile("/tmp/.kit.yml"),
+		kit.WithStreaming(false),
+		kit.WithDebug(),
+		kit.Ephemeral(),
+	}
+	for _, fn := range opts {
+		fn(o)
+	}
+
+	if o.Model != "anthropic/claude-sonnet-4-5-20250929" {
+		t.Errorf("WithModel: got %q", o.Model)
+	}
+	if o.SystemPrompt != "be terse" {
+		t.Errorf("WithSystemPrompt: got %q", o.SystemPrompt)
+	}
+	if o.MaxTokens != 4321 {
+		t.Errorf("WithMaxTokens: got %d", o.MaxTokens)
+	}
+	if o.ThinkingLevel != "high" {
+		t.Errorf("WithThinkingLevel: got %q", o.ThinkingLevel)
+	}
+	if o.ProviderAPIKey != "sk-test" {
+		t.Errorf("WithProviderAPIKey: got %q", o.ProviderAPIKey)
+	}
+	if o.ProviderURL != "https://example.test/v1" {
+		t.Errorf("WithProviderURL: got %q", o.ProviderURL)
+	}
+	if o.ConfigFile != "/tmp/.kit.yml" {
+		t.Errorf("WithConfigFile: got %q", o.ConfigFile)
+	}
+	if o.Streaming == nil {
+		t.Error("WithStreaming: expected Streaming to be set (non-nil)")
+	} else if *o.Streaming {
+		t.Error("WithStreaming(false): expected *Streaming=false")
+	}
+	if !o.Debug {
+		t.Error("WithDebug: expected Debug=true")
+	}
+	if !o.NoSession {
+		t.Error("Ephemeral: expected NoSession=true")
+	}
+}
+
+// TestOptionOrderingOverrides verifies later options override earlier ones.
+func TestOptionOrderingOverrides(t *testing.T) {
+	o := &kit.Options{}
+	kit.WithModel("a/b")(o)
+	kit.WithModel("c/d")(o)
+	if o.Model != "c/d" {
+		t.Errorf("later WithModel should win; got %q", o.Model)
+	}
+}
+
+// TestKitConfigIsolation is the regression test for issue #40: two Kit
+// instances constructed in the same process must own independent configuration
+// stores. Setting the thinking level (or model) on one must not affect the
+// other. Against the previous global-viper implementation this test fails
+// because both Kits read and write the same process-global store.
+func TestKitConfigIsolation(t *testing.T) {
+	if os.Getenv("ANTHROPIC_API_KEY") == "" {
+		t.Skip("Skipping test: ANTHROPIC_API_KEY not set")
+	}
+
+	ctx := context.Background()
+
+	a, err := kit.New(ctx, &kit.Options{
+		Model:         "anthropic/claude-sonnet-4-5-20250929",
+		ThinkingLevel: "low",
+		Quiet:         true,
+		NoSession:     true,
+		NoExtensions:  true,
+	})
+	if err != nil {
+		t.Fatalf("failed to create Kit A: %v", err)
+	}
+	defer func() { _ = a.Close() }()
+
+	b, err := kit.New(ctx, &kit.Options{
+		Model:         "anthropic/claude-sonnet-4-5-20250929",
+		ThinkingLevel: "high",
+		Quiet:         true,
+		NoSession:     true,
+		NoExtensions:  true,
+	})
+	if err != nil {
+		t.Fatalf("failed to create Kit B: %v", err)
+	}
+	defer func() { _ = b.Close() }()
+
+	// Each instance must retain its own configured thinking level. Under the
+	// old global-viper implementation, B's construction overwrote A's value.
+	if got := a.GetThinkingLevel(); got != "low" {
+		t.Errorf("Kit A thinking level = %q; want %q (config leaked from B)", got, "low")
+	}
+	if got := b.GetThinkingLevel(); got != "high" {
+		t.Errorf("Kit B thinking level = %q; want %q", got, "high")
+	}
+
+	// Mutating one at runtime must not bleed into the other.
+	if err := a.SetThinkingLevel(ctx, "medium"); err != nil {
+		t.Fatalf("SetThinkingLevel on A: %v", err)
+	}
+	if got := a.GetThinkingLevel(); got != "medium" {
+		t.Errorf("after SetThinkingLevel, Kit A = %q; want %q", got, "medium")
+	}
+	if got := b.GetThinkingLevel(); got != "high" {
+		t.Errorf("after mutating A, Kit B leaked to %q; want %q", got, "high")
+	}
+}
+
+// TestNewAgentDefaultsStreamingOn verifies that the ergonomic constructor
+// enables streaming by default and applies functional options.
+func TestNewAgentDefaultsStreamingOn(t *testing.T) {
+	if os.Getenv("ANTHROPIC_API_KEY") == "" {
+		t.Skip("Skipping test: ANTHROPIC_API_KEY not set")
+	}
+
+	ctx := context.Background()
+	k, err := kit.NewAgent(ctx,
+		kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+		kit.WithMaxTokens(2048),
+		kit.Ephemeral(),
+	)
+	if err != nil {
+		t.Fatalf("NewAgent failed: %v", err)
+	}
+	defer func() { _ = k.Close() }()
+
+	if !k.ConfigValueIsSetForTest("max-tokens") {
+		t.Error("NewAgent did not propagate WithMaxTokens to the instance store")
+	}
+	if !k.ConfigBoolForTest("stream") {
+		t.Error("NewAgent should enable streaming by default")
+	}
+}
+
+// TestNewAgentStreamingOptOut verifies WithStreaming(false) disables the
+// default-on streaming behaviour of NewAgent.
+func TestNewAgentStreamingOptOut(t *testing.T) {
+	if os.Getenv("ANTHROPIC_API_KEY") == "" {
+		t.Skip("Skipping test: ANTHROPIC_API_KEY not set")
+	}
+
+	ctx := context.Background()
+	k, err := kit.NewAgent(ctx,
+		kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+		kit.WithStreaming(false),
+		kit.Ephemeral(),
+	)
+	if err != nil {
+		t.Fatalf("NewAgent failed: %v", err)
+	}
+	defer func() { _ = k.Close() }()
+
+	if k.ConfigBoolForTest("stream") {
+		t.Error("WithStreaming(false) should disable streaming")
+	}
+}
+
+// TestNewZeroOptionsKeepsStreamingDefault is the regression test for the
+// unconditional `v.Set("stream", opts.Streaming)` bug: a zero-valued Options
+// (Streaming == nil) must NOT force stream=false. With Streaming unset,
+// streaming resolves through the precedence chain, whose SDK default is true.
+func TestNewZeroOptionsKeepsStreamingDefault(t *testing.T) {
+	if os.Getenv("ANTHROPIC_API_KEY") == "" {
+		t.Skip("Skipping test: ANTHROPIC_API_KEY not set")
+	}
+
+	ctx := context.Background()
+	k, err := kit.New(ctx, &kit.Options{
+		Model:      "anthropic/claude-sonnet-4-5-20250929",
+		Quiet:      true,
+		NoSession:  true,
+		SkipConfig: true, // isolate from any ~/.kit.yml / env stream setting
+	})
+	if err != nil {
+		t.Fatalf("New failed: %v", err)
+	}
+	defer func() { _ = k.Close() }()
+
+	if !k.ConfigBoolForTest("stream") {
+		t.Error("zero-valued Options must not force stream=false; expected the default (true)")
+	}
+}
+
+// TestNewStreamingExplicitOptOut verifies that a raw Options can still disable
+// streaming by setting Streaming to a pointer to false.
+func TestNewStreamingExplicitOptOut(t *testing.T) {
+	if os.Getenv("ANTHROPIC_API_KEY") == "" {
+		t.Skip("Skipping test: ANTHROPIC_API_KEY not set")
+	}
+
+	streamOff := false
+	ctx := context.Background()
+	k, err := kit.New(ctx, &kit.Options{
+		Model:      "anthropic/claude-sonnet-4-5-20250929",
+		Quiet:      true,
+		NoSession:  true,
+		SkipConfig: true,
+		Streaming:  &streamOff,
+	})
+	if err != nil {
+		t.Fatalf("New failed: %v", err)
+	}
+	defer func() { _ = k.Close() }()
+
+	if k.ConfigBoolForTest("stream") {
+		t.Error("Streaming=&false should disable streaming")
+	}
+}

www/pages/configuration.md

@@ -88,6 +88,9 @@ mcpServers:
     type: remote
     url: "https://pubmed.mcp.example.com"
     noOAuth: true  # skip OAuth for public servers
+    headers:
+      - "ApiKey: ${env://API_KEY}"              # required env var
+      - "X-Tenant: ${env://TENANT_ID:-default}" # with fallback default
 
   builds:
     type: remote
@@ -106,9 +109,10 @@ mcpServers:
 | `allowedTools` | list | Whitelist of tool names to expose |
 | `excludedTools` | list | Blacklist of tool names to hide |
 | `noOAuth` | bool | Skip OAuth for this server (for public servers that don't require auth) |
+| `headers` | list of strings | HTTP headers to attach to every request, each as a `"Key: Value"` string. Values support env-substitution: `${env://VAR}` or `${env://VAR:-default}`. |
 | `tasksMode` | string | When to augment `tools/call` with MCP task metadata: `auto` (default — only when the server advertises task support), `never`, or `always`. See [MCP tasks](#mcp-tasks-long-running-tools). |
 
-A legacy format with `transport`, `args`, `env`, and `headers` fields is also supported.
+A legacy format with `transport`, `args`, and `env` fields is also supported; `headers` works in both the current and legacy formats.
 
 ### MCP tasks (long-running tools)
 

www/pages/providers.md

@@ -143,6 +143,39 @@ The `custom/custom` model has zero cost, 262K context window, and supports reaso
 
 Optionally set `CUSTOM_API_KEY` environment variable or use `--provider-api-key` for endpoints requiring authentication.
 
+## Auto-routed providers
+
+Any provider in the [models.dev](https://models.dev) database can be used with the
+standard `provider/model` format, even without a dedicated native integration. Kit
+auto-routes the request through the matching **wire protocol** — the actual API
+shape the provider speaks — rather than requiring a per-provider code path:
+
+| Wire protocol | npm package (models.dev) | Transport used |
+|---------------|--------------------------|----------------|
+| OpenAI (Responses API) | `@ai-sdk/openai` | OpenAI |
+| OpenAI (chat completions) | `@ai-sdk/openai-compatible` | OpenAI-compatible |
+| Anthropic | `@ai-sdk/anthropic` | Anthropic |
+| Google Gemini | `@ai-sdk/google` | Google |
+
+The provider's `api` URL from the database is used as the base URL. A provider
+whose npm package isn't recognized but that has an `api` URL falls back to the
+OpenAI-compatible wire.
+
+Because routing follows the wire protocol, aggregator/proxy providers work across
+**all** of their models — including ones they re-flavor onto a different protocol
+via a per-model override. For example, an aggregator that proxies Claude, GPT,
+*and* Gemini routes them to the Anthropic, OpenAI, and Google transports
+respectively:
+
+```bash
+kit --model opencode/claude-haiku-4-5 "Hello"     # → Anthropic wire
+kit --model opencode/gpt-5 "Hello"                # → OpenAI wire
+kit --model opencode/gemini-3.5-flash "Hello"     # → Google wire
+```
+
+Provide the provider's API key the same way as any other — via its environment
+variable (e.g. `OPENCODE_API_KEY`) or `--provider-api-key`.
+
 ## Model database
 
 Kit ships with a local model database that maps provider names to API configurations. You can manage it with:

www/pages/sdk/options.md

@@ -7,6 +7,16 @@ description: Configuration options for the Kit Go SDK.
 
 Pass an `Options` struct to `kit.New()` to configure the Kit instance.
 
+::: tip
+For simple setups, `kit.NewAgent(ctx, ...Option)` provides functional-options
+helpers (`WithModel`, `WithStreaming`, `Ephemeral`, ...) over the same `Options`
+struct. See [Functional options](/sdk/overview#functional-options-newagent).
+:::
+
+Each `kit.New` / `kit.NewAgent` call owns an isolated configuration store, so
+these options never leak between Kit instances in the same process. See
+[Per-instance config isolation](/sdk/overview#per-instance-config-isolation).
+
 ## Full options reference
 
 ```go
@@ -18,7 +28,7 @@ host, err := kit.New(ctx, &kit.Options{
 
     // Behavior
     MaxSteps:     10,
-    Streaming:    true,
+    Streaming:    ptrBool(true), // *bool: nil = unset (default true), &false = off
     Quiet:        true,
     Debug:        true,
 
@@ -91,7 +101,7 @@ host, err := kit.New(ctx, &kit.Options{
 | `SystemPrompt` | `string` | — | System prompt text or file path |
 | `ConfigFile` | `string` | `~/.kit.yml` | Path to config file |
 | `MaxSteps` | `int` | `0` | Max agent steps (0 = unlimited) |
-| `Streaming` | `bool` | `true` | Enable streaming output |
+| `Streaming` | `*bool` | `nil` | Enable streaming output. `nil` leaves it to the precedence chain (env → config → default `true`); `&true`/`&false` forces it. Pointer so unset is distinct from explicit `false`. |
 | `Quiet` | `bool` | `false` | Suppress output |
 | `Debug` | `bool` | `false` | Enable debug logging |
 
@@ -114,9 +124,10 @@ defaults for samplers).
 | `FrequencyPenalty` | `*float32` | — | OpenAI-family frequency penalty. `nil` leaves provider default. |
 | `PresencePenalty` | `*float32` | — | OpenAI-family presence penalty. `nil` leaves provider default. |
 
-Pointer-typed samplers are populated via a tiny helper:
+Pointer-typed fields (`Streaming` and the samplers) are populated via tiny helpers:
 
 ```go
+func ptrBool(v bool) *bool          { return &v }
 func ptrFloat32(v float32) *float32 { return &v }
 ```
 
@@ -127,7 +138,7 @@ when embedding Kit as a library.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `ProviderAPIKey` | `string` | — | API key used to authenticate with the provider. `""` falls back to config / provider-specific env var (e.g. `ANTHROPIC_API_KEY`). When set, overrides any pre-existing viper state. |
+| `ProviderAPIKey` | `string` | — | API key used to authenticate with the provider. `""` falls back to config / provider-specific env var (e.g. `ANTHROPIC_API_KEY`). When set, it takes precedence over config and env values on this instance's store. |
 | `ProviderURL` | `string` | — | Override the provider endpoint (e.g. LiteLLM, vLLM, Azure OpenAI, internal proxy). `""` = provider default. |
 | `TLSSkipVerify` | `bool` | `false` | Disable TLS certificate verification on the provider HTTP client. Only effective when `true`; to force-disable, use config file or env var instead. For self-signed dev certs only. |
 
@@ -160,6 +171,14 @@ when embedding Kit as a library.
 | `SkillsDir` | `string` | — | Override default skills directory |
 | `NoSkills` | `bool` | `false` | Disable skill loading entirely |
 
+These fields only control the **initial** skill and context-file set picked
+up by `New()`. To add, remove, or replace skills and `AGENTS.md`-style
+context files at runtime (e.g. per user or per session), use the
+`AddSkill` / `LoadAndAddSkill` / `RemoveSkill` / `SetSkills` and
+`AddContextFile` / `AddContextFileContent` / `RemoveContextFile` /
+`SetContextFiles` methods on `*kit.Kit`. See
+[Runtime skills and context files](/sdk/overview#runtime-skills-and-context-files).
+
 ### Compaction & MCP
 
 | Field | Type | Default | Description |

www/pages/sdk/overview.md

@@ -45,6 +45,73 @@ func main() {
 }
 ```
 
+## Functional options (`NewAgent`)
+
+For simple programmatic setups, `kit.NewAgent` offers an ergonomic
+functional-options front door over `kit.New`. Streaming is **enabled by
+default**; pass `kit.WithStreaming(false)` to opt out.
+
+```go
+host, err := kit.NewAgent(ctx,
+    kit.WithModel("anthropic/claude-sonnet-4-5-20250929"),
+    kit.WithSystemPrompt("You are a helpful assistant."),
+    kit.WithMaxTokens(8192),
+    kit.WithThinkingLevel("medium"),
+    kit.Ephemeral(), // in-memory session, no persistence
+)
+if err != nil {
+    log.Fatal(err)
+}
+defer host.Close()
+```
+
+Available options:
+
+| Option | Sets |
+|--------|------|
+| `WithModel(string)` | `Options.Model` (provider/model format) |
+| `WithSystemPrompt(string)` | `Options.SystemPrompt` (inline text or file path) |
+| `WithStreaming(bool)` | `Options.Streaming` (default `true` under `NewAgent`) |
+| `WithMaxTokens(int)` | `Options.MaxTokens` |
+| `WithThinkingLevel(string)` | `Options.ThinkingLevel` |
+| `WithTools(...Tool)` | `Options.Tools` (replaces the default set) |
+| `WithExtraTools(...Tool)` | `Options.ExtraTools` (adds alongside defaults) |
+| `WithProviderAPIKey(string)` | `Options.ProviderAPIKey` |
+| `WithProviderURL(string)` | `Options.ProviderURL` |
+| `WithConfigFile(string)` | `Options.ConfigFile` |
+| `WithDebug()` | `Options.Debug = true` |
+| `Ephemeral()` | `Options.NoSession = true` |
+
+Options are applied in order, so later options override earlier ones. `Option`
+is a plain `func(*Options)`, so you can define your own. For advanced
+configuration not covered by the helpers (custom MCP config, in-process MCP
+servers, session backends, MCP task tuning) construct an `Options` value
+explicitly and call `kit.New`.
+
+### When to use which
+
+| Constructor | Use when |
+|-------------|----------|
+| `kit.NewAgent(ctx, ...Option)` | Quick programmatic setups; you only need the common fields. Streaming defaults on. |
+| `kit.New(ctx, *Options)` | You need fields without a `With*` helper (`MCPConfig`, `InProcessMCPServers`, `SessionManager`, MCP task tuning, etc.), or you already hold an `Options` value. |
+
+## Per-instance config isolation
+
+Each `kit.New` / `kit.NewAgent` call owns an **isolated configuration store**,
+so constructing multiple Kit instances in the same process is safe: setting the
+model, thinking level, or generation parameters on one never affects another,
+and runtime mutators (`SetModel`, `SetThinkingLevel`) only touch the owning
+instance. This makes subagent spawning and multi-Kit embedding race-free with
+no external synchronization required.
+
+```go
+a, _ := kit.NewAgent(ctx, kit.WithThinkingLevel("low"))
+b, _ := kit.NewAgent(ctx, kit.WithThinkingLevel("high"))
+
+a.SetThinkingLevel(ctx, "medium")
+// a.GetThinkingLevel() == "medium"; b.GetThinkingLevel() is still "high"
+```
+
 ## Multi-turn conversations
 
 Conversations retain context automatically across calls:
@@ -201,6 +268,66 @@ host, _ := kit.New(ctx, &kit.Options{
 n, _ := host.AddInProcessMCPServer(ctx, "docs", mcpSrv)
 ```
 
+## Runtime skills and context files
+
+Kit auto-discovers skills and `AGENTS.md`-style context files during `New()`,
+but multi-tenant hosts (chatbots, web services, per-user agents) often need
+to swap these **after** construction. The runtime mutators below recompose
+the system prompt and apply it to the agent so the next turn picks up the
+updated instructions — no restart, no file shuffling.
+
+```go
+// Add a programmatic skill — no file on disk required.
+host.AddSkill(&kit.Skill{
+    Name:        "polite-french",
+    Description: "Respond in French and always greet the user.",
+    Content:     "Always reply in French. Open every response with 'Bonjour'.",
+})
+
+// Or load one from disk.
+host.LoadAndAddSkill("/var/skills/refund-policy.md")
+
+// Project context (AGENTS.md equivalents): inline content from a DB...
+host.AddContextFileContent(
+    fmt.Sprintf("session://%s/AGENTS.md", userID),
+    rulesFromDB,
+)
+// ...or load from disk.
+host.LoadAndAddContextFile("/etc/agents/tenant-acme.md")
+
+// Remove individually when a session ends.
+host.RemoveSkill("polite-french")
+host.RemoveContextFile(fmt.Sprintf("session://%s/AGENTS.md", userID))
+
+// Or replace the whole set in one call.
+host.SetSkills(activeSkillsForUser)
+host.SetContextFiles(activeContextForUser)
+
+// Inspect current state (snapshot copies — safe to mutate).
+skills := host.GetSkills()
+ctxFiles := host.GetContextFiles()
+```
+
+Key points:
+
+- **Auto-refresh.** Every `Add*` / `Remove*` / `Set*` call recomposes the system
+  prompt against the captured base prompt (preserving per-model overrides and
+  `--system-prompt` resolution) and pushes the result onto the agent. Call
+  `host.RefreshSystemPrompt()` only if you mutate state through a different
+  path and need to force a re-render.
+- **Dedup keys.** Skills dedupe by `Name`; context files dedupe by `Path`.
+  Re-adding the same key replaces the entry instead of appending a duplicate.
+- **Path is opaque.** `ContextFile.Path` does not have to point at a real file
+  — it's only used for dedup and for the `Instructions from: <Path>` header
+  injected into the prompt. URIs like `session://user-123/AGENTS.md` work fine.
+- **Thread safety.** All readers and mutators are safe to call concurrently
+  from multiple goroutines; the underlying state is guarded by an internal
+  `RWMutex`.
+- **Init-time options still apply.** `Options.Skills`, `Options.SkillsDir`,
+  `Options.NoSkills`, and `Options.NoContextFiles` continue to control the
+  startup set; the runtime API mutates from whatever state `New()` produced.
+  See [SDK options](/sdk/options#skills--configuration).
+
 ## MCP prompts and resources
 
 Query prompts and resources exposed by connected MCP servers: