Resolve conflicts in agent_media.go

.dockerignore

@@ -1,3 +1,5 @@
+# Do NOT exclude LICENSE or .github — scripts/copydir.go uses them as repo-root anchors
+# during `go generate`, which runs inside `make build` in the Dockerfile.
 .git
 .gitignore
 build/
@@ -6,5 +8,4 @@ config/
 .env
 .env.example
 *.md
-LICENSE
 assets/

.gitattributes

@@ -0,0 +1,3 @@
+# Ensure shell scripts always use LF line endings regardless of OS.
+*.sh text eol=lf
+docker/entrypoint.sh text eol=lf

.github/workflows/stale.yml

@@ -0,0 +1,64 @@
+name: Close stale issues and PRs
+
+on:
+  schedule:
+    # Run daily at 03:00 JST (18:00 UTC)
+    - cron: "0 18 * * *"
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Mark and close stale issues and PRs
+        uses: actions/stale@v10
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+          # ── Issue: 7 days inactive → stale; 7 more days → close ──
+          days-before-issue-stale: 7
+          days-before-issue-close: 7
+          stale-issue-label: "stale"
+          stale-issue-message: >
+            This issue has had no activity for 7 days and has been marked as stale.
+            If it is still relevant, please reply or update; otherwise it will be
+            closed automatically in 7 days.
+          close-issue-message: >
+            This issue has been closed after 14 days of inactivity.
+            If it is still needed, feel free to reopen it anytime.
+          close-issue-reason: "not_planned"
+
+          # ── PR: 7 days inactive → stale; 7 more days → close ──
+          days-before-pr-stale: 7
+          days-before-pr-close: 7
+          stale-pr-label: "stale"
+          stale-pr-message: >
+            This PR has had no activity for 7 days and has been marked as stale.
+            If you are still working on it, please push an update or leave a comment;
+            otherwise it will be closed automatically in 7 days.
+          close-pr-message: >
+            This PR has been closed after 14 days of inactivity.
+            If you would like to continue, feel free to reopen it or submit a new PR.
+
+          # ── Protected labels (exempt from stale processing) ──
+          exempt-issue-labels: "pinned,keep-open,wip,do-not-close,type: roadmap"
+          exempt-pr-labels: "pinned,keep-open,wip,do-not-close,type: roadmap"
+
+          # ── Exempt draft PRs ──
+          exempt-draft-pr: true
+
+          # ── Remove stale label when activity resumes ──
+          remove-stale-when-updated: true
+          remove-issue-stale-when-updated: true
+          remove-pr-stale-when-updated: true
+
+          # ── Scan oldest items first so old stale items are not starved ──
+          ascending: true
+
+          # ── Throttle: max operations per run ──
+          operations-per-run: 500

.gitignore

@@ -55,6 +55,10 @@ dist/
 
 # Windows Application Icon/Resource
 *.syso
+.cache/
+web/frontend/.pnpm-store/
+_tmp_*
+web/frontend/_tmp_*
 
 # Test telegram integration
 cmd/telegram/

.goreleaser.yaml

@@ -100,49 +100,6 @@ builds:
       - goos: netbsd
         goarch: arm
 
-  - id: picoclaw-launcher-tui
-    binary: picoclaw-launcher-tui
-    env:
-      - CGO_ENABLED=0
-    tags:
-      - goolm
-      - stdjson
-    ldflags:
-      - -s -w
-      - -X github.com/sipeed/picoclaw/pkg/config.Version={{ .Version }}
-      - -X github.com/sipeed/picoclaw/pkg/config.GitCommit={{ .ShortCommit }}
-      - -X github.com/sipeed/picoclaw/pkg/config.BuildTime={{ .Date }}
-      - -X github.com/sipeed/picoclaw/pkg/config.GoVersion={{ with index .Env "GOVERSION" }}{{ . }}{{ else }}unknown{{ end }}
-    goos:
-      - linux
-      - windows
-      - darwin
-      - freebsd
-      - netbsd
-    goarch:
-      - amd64
-      - arm64
-      - riscv64
-      - loong64
-      - arm
-      - s390x
-      - mipsle
-    goarm:
-      - "6"
-      - "7"
-    gomips:
-      - softfloat
-    main: ./cmd/picoclaw-launcher-tui
-    ignore:
-      - goos: windows
-        goarch: arm
-      - goos: netbsd
-        goarch: s390x
-      - goos: netbsd
-        goarch: mips64
-      - goos: netbsd
-        goarch: arm
-
 dockers_v2:
   - id: picoclaw
     dockerfile: docker/Dockerfile.goreleaser
@@ -166,7 +123,6 @@ dockers_v2:
     ids:
       - picoclaw
       - picoclaw-launcher
-      - picoclaw-launcher-tui
     images:
       - "ghcr.io/{{ .Env.GITHUB_REPOSITORY_OWNER }}/picoclaw"
       - 'docker.io/{{ .Env.DOCKERHUB_IMAGE_NAME }}'
@@ -184,7 +140,6 @@ notarize:
       ids:
         - picoclaw
         - picoclaw-launcher
-        - picoclaw-launcher-tui
       sign:
         certificate: "{{.Env.MACOS_SIGN_P12}}"
         password: "{{.Env.MACOS_SIGN_PASSWORD}}"
@@ -215,7 +170,6 @@ nfpms:
     ids:
       - picoclaw
       - picoclaw-launcher
-      - picoclaw-launcher-tui
     package_name: picoclaw
     file_name_template: >-
       {{ .PackageName }}_

Makefile

@@ -7,19 +7,43 @@ CMD_DIR=cmd/$(BINARY_NAME)
 MAIN_GO=$(CMD_DIR)/main.go
 EXT=
 
+ifeq ($(OS),Windows_NT)
+	POWERSHELL=powershell -NoProfile -Command
+	WINDOWS_GOARCH_RAW:=$(strip $(shell go env GOARCH 2>NUL))
+endif
+
 # Version
-VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
-GIT_COMMIT=$(shell git rev-parse --short=8 HEAD 2>/dev/null || echo "dev")
-BUILD_TIME=$(shell date +%FT%T%z)
-GO_VERSION=$(shell $(GO) version | awk '{print $$3}')
+ifeq ($(OS),Windows_NT)
+	VERSION_RAW:=$(strip $(shell git describe --tags --always --dirty 2>NUL))
+	GIT_COMMIT_RAW:=$(strip $(shell git rev-parse --short=8 HEAD 2>NUL))
+	BUILD_TIME_RAW:=$(strip $(shell powershell -NoProfile -Command "Get-Date -Format 'yyyy-MM-ddTHH:mm:ssK'"))
+	GO_VERSION_RAW:=$(strip $(shell go env GOVERSION 2>NUL))
+else
+	VERSION_RAW:=$(strip $(shell git describe --tags --always --dirty 2>/dev/null))
+	GIT_COMMIT_RAW:=$(strip $(shell git rev-parse --short=8 HEAD 2>/dev/null))
+	BUILD_TIME_RAW:=$(strip $(shell date +%FT%T%z))
+	GO_VERSION_RAW:=$(strip $(shell go env GOVERSION 2>/dev/null))
+endif
+VERSION?=$(if $(VERSION_RAW),$(VERSION_RAW),dev)
+GIT_COMMIT=$(if $(GIT_COMMIT_RAW),$(GIT_COMMIT_RAW),dev)
+BUILD_TIME=$(if $(BUILD_TIME_RAW),$(BUILD_TIME_RAW),dev)
+GO_VERSION=$(if $(GO_VERSION_RAW),$(GO_VERSION_RAW),unknown)
 CONFIG_PKG=github.com/sipeed/picoclaw/pkg/config
 LDFLAGS=-X $(CONFIG_PKG).Version=$(VERSION) -X $(CONFIG_PKG).GitCommit=$(GIT_COMMIT) -X $(CONFIG_PKG).BuildTime=$(BUILD_TIME) -X $(CONFIG_PKG).GoVersion=$(GO_VERSION) -s -w
 
 # Go variables
-GO?=CGO_ENABLED=0 go
+GO?=go
 WEB_GO?=$(GO)
+CGO_ENABLED?=0
 GO_BUILD_TAGS?=goolm,stdjson
 GOFLAGS?=-v -tags $(GO_BUILD_TAGS)
+GOCACHE?=$(CURDIR)/.cache/go-build
+GOMODCACHE?=$(CURDIR)/.cache/go-mod
+GOTOOLCHAIN?=local
+export CGO_ENABLED
+export GOCACHE
+export GOMODCACHE
+export GOTOOLCHAIN
 comma:=,
 empty:=
 space:=$(empty) $(empty)
@@ -73,8 +97,21 @@ BUILTIN_SKILLS_DIR=$(CURDIR)/skills
 LNCMD=ln -sf
 
 # OS detection
-UNAME_S?=$(shell uname -s)
-UNAME_M?=$(shell uname -m)
+ifeq ($(OS),Windows_NT)
+	UNAME_S=Windows
+	ifeq ($(WINDOWS_GOARCH_RAW),amd64)
+		UNAME_M=x86_64
+	else ifeq ($(WINDOWS_GOARCH_RAW),arm64)
+		UNAME_M=arm64
+	else ifeq ($(WINDOWS_GOARCH_RAW),386)
+		UNAME_M=x86
+	else
+		UNAME_M=$(if $(WINDOWS_GOARCH_RAW),$(WINDOWS_GOARCH_RAW),x86_64)
+	endif
+else
+	UNAME_S?=$(shell uname -s)
+	UNAME_M?=$(shell uname -m)
+endif
 
 # Platform-specific settings
 ifeq ($(UNAME_S),Linux)
@@ -122,6 +159,30 @@ else
 
 endif
 
+ifeq ($(OS),Windows_NT)
+	PLATFORM=windows
+	ifeq ($(UNAME_M),x86_64)
+		ARCH?=amd64
+	else ifeq ($(UNAME_M),arm64)
+		ARCH?=arm64
+	else
+		ARCH?=$(UNAME_M)
+	endif
+	EXT=.exe
+endif
+
+ifneq ($(strip $(GOOS)),)
+	PLATFORM:=$(GOOS)
+endif
+
+ifneq ($(strip $(GOARCH)),)
+	ARCH:=$(GOARCH)
+endif
+
+ifeq ($(PLATFORM),windows)
+	EXT=.exe
+endif
+
 BINARY_PATH=$(BUILD_DIR)/$(BINARY_NAME)-$(PLATFORM)-$(ARCH)
 
 # Default target
@@ -130,41 +191,51 @@ all: build
 ## generate: Run generate
 generate:
 	@echo "Run generate..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "if (Test-Path -LiteralPath './$(CMD_DIR)/workspace') { Remove-Item -LiteralPath './$(CMD_DIR)/workspace' -Recurse -Force }"
+	@$(POWERSHELL) "$$env:GOOS=''; $$env:GOARCH=''; $(GO) generate ./..."
+else
 	@rm -r ./$(CMD_DIR)/workspace 2>/dev/null || true
-	@$(GO) generate ./...
+	@GOOS=$$($(GO) env GOHOSTOS) GOARCH=$$($(GO) env GOHOSTARCH) $(GO) generate ./...
+endif
 	@echo "Run generate complete"
 
 ## build: Build the picoclaw binary for current platform
 build: generate
 	@echo "Building $(BINARY_NAME)$(EXT) for $(PLATFORM)/$(ARCH)..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "New-Item -ItemType Directory -Force -Path '$(BUILD_DIR)' | Out-Null"
+	@$(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY_PATH)$(EXT) ./$(CMD_DIR)
+	@$(POWERSHELL) "Copy-Item -LiteralPath '$(BINARY_PATH)$(EXT)' -Destination '$(BUILD_DIR)/$(BINARY_NAME)$(EXT)' -Force"
+else
 	@mkdir -p $(BUILD_DIR)
-	@GOARCH=${ARCH} $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY_PATH)$(EXT) ./$(CMD_DIR)
+	@GOOS=$(PLATFORM) GOARCH=$(ARCH) $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY_PATH)$(EXT) ./$(CMD_DIR)
 	@echo "Build complete: $(BINARY_PATH)$(EXT)"
 	@$(LNCMD) $(BINARY_NAME)-$(PLATFORM)-$(ARCH)$(EXT) $(BUILD_DIR)/$(BINARY_NAME)$(EXT)
+endif
+	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)$(EXT)"
 
 ## build-launcher: Build the picoclaw-launcher (web console) binary
 build-launcher:
 	@echo "Building picoclaw-launcher for $(PLATFORM)/$(ARCH)..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "New-Item -ItemType Directory -Force -Path '$(BUILD_DIR)' | Out-Null"
+	@$(MAKE) -C web build PLATFORM="$(PLATFORM)" ARCH="$(ARCH)" EXT="$(EXT)" OUTPUT="$(CURDIR)/$(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT)" GO_BUILD_TAGS="$(GO_BUILD_TAGS)"
+	@$(POWERSHELL) "Copy-Item -LiteralPath '$(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT)' -Destination '$(BUILD_DIR)/picoclaw-launcher$(EXT)' -Force"
+else
 	@mkdir -p $(BUILD_DIR)
-	@GOARCH=${ARCH} $(MAKE) -C web build \
+	@GOOS=$(PLATFORM) GOARCH=$(ARCH) $(MAKE) -C web build \
 		OUTPUT="$(CURDIR)/$(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT)" \
 		WEB_GO='$(WEB_GO)' \
 		GO_BUILD_TAGS='$(GO_BUILD_TAGS)' \
 		LDFLAGS='$(LDFLAGS)'
 	@$(LNCMD) picoclaw-launcher-$(PLATFORM)-$(ARCH)$(EXT) $(BUILD_DIR)/picoclaw-launcher$(EXT)
+endif
 	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher$(EXT)"
 
 build-launcher-frontend:
 	@$(MAKE) -C web build-frontend
 
-## build-launcher-tui: Build the picoclaw-launcher TUI binary
-build-launcher-tui:
-	@echo "Building picoclaw-launcher-tui for $(PLATFORM)/$(ARCH)..."
-	@mkdir -p $(BUILD_DIR)
-	@$(GO) build $(GOFLAGS) -o $(BUILD_DIR)/picoclaw-launcher-tui-$(PLATFORM)-$(ARCH) ./cmd/picoclaw-launcher-tui
-	@ln -sf picoclaw-launcher-tui-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/picoclaw-launcher-tui
-	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher-tui"
-
 ## build-whatsapp-native: Build with WhatsApp native (whatsmeow) support; larger binary
 build-whatsapp-native: generate
 ## @echo "Building $(BINARY_NAME) with WhatsApp native for $(PLATFORM)/$(ARCH)..."
@@ -290,7 +361,11 @@ uninstall-all:
 ## clean: Remove build artifacts
 clean:
 	@echo "Cleaning build artifacts..."
+ifeq ($(OS),Windows_NT)
+	@$(POWERSHELL) "if (Test-Path -LiteralPath '$(BUILD_DIR)') { Remove-Item -LiteralPath '$(BUILD_DIR)' -Recurse -Force }"
+else
 	@rm -rf $(BUILD_DIR)
+endif
 	@echo "Clean complete"
 
 ## vet: Run go vet for static analysis

README.md

@@ -291,24 +291,6 @@ After this one-time step, `picoclaw-launcher` will open normally on subsequent l
 
 </details>
 
-### 💻 TUI Launcher (Recommended for Headless / SSH)
-
-The TUI (Terminal UI) Launcher provides a full-featured terminal interface for configuration and management. Ideal for servers, Raspberry Pi, and other headless environments.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Getting started:**
-
-Use the TUI menus to: **1)** Configure a Provider -> **2)** Configure a Channel -> **3)** Start the Gateway -> **4)** Chat!
-
-For detailed TUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 
@@ -571,7 +553,20 @@ PicoClaw natively supports [MCP](https://modelcontextprotocol.io/) — connect a
 }
 ```
 
-For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/reference/tools_configuration.md#mcp-tool).
+You can manage common MCP setups directly from the CLI instead of editing JSON by hand:
+
+```bash
+picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
+picoclaw mcp list
+picoclaw mcp test filesystem
+```
+
+`picoclaw mcp` is a configuration manager: it updates `config.json` under `tools.mcp.servers`, but it does not keep the server process running itself.
+
+Use `picoclaw mcp edit` when you need advanced fields that are not covered by `picoclaw mcp add`.
+For example, `picoclaw mcp add` supports `--deferred` and `--env-file`, while `picoclaw mcp edit` is still useful for direct JSON editing and uncommon MCP settings.
+
+For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/reference/tools_configuration.md#mcp-tool). For CLI usage and examples, see [MCP Server CLI](docs/reference/mcp-cli.md).
 
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
 
@@ -591,6 +586,11 @@ Connect PicoClaw to the Agent Social Network simply by sending a single message
 | `picoclaw status`         | Show status                      |
 | `picoclaw version`        | Show version info                |
 | `picoclaw model`          | View or switch the default model |
+| `picoclaw mcp list`       | List configured MCP servers      |
+| `picoclaw mcp add ...`    | Add or update an MCP server entry |
+| `picoclaw mcp test`       | Probe a configured MCP server    |
+| `picoclaw mcp edit`       | Open config for advanced MCP editing |
+| `picoclaw mcp remove`     | Remove an MCP server entry       |
 | `picoclaw cron list`      | List all scheduled jobs          |
 | `picoclaw cron add ...`   | Add a scheduled job              |
 | `picoclaw cron disable`   | Disable a scheduled job          |
@@ -619,6 +619,7 @@ For detailed guides beyond this README:
 | [Docker & Quick Start](docs/guides/docker.md) | Docker Compose setup, Launcher/Agent modes |
 | [Chat Apps](docs/guides/chat-apps.md) | All 17+ channel setup guides |
 | [Configuration](docs/guides/configuration.md) | Environment variables, workspace layout, security sandbox |
+| [MCP Server CLI](docs/reference/mcp-cli.md) | Add, list, test, edit, and remove MCP server entries from the CLI |
 | [Scheduled Tasks and Cron Jobs](docs/reference/cron.md) | Cron schedule types, deliver modes, command gates, job storage |
 | [Providers & Models](docs/guides/providers.md) | 30+ LLM providers, model routing, model_list configuration |
 | [Spawn & Async Tasks](docs/guides/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |

cmd/picoclaw-launcher-tui/README.md

@@ -1,69 +0,0 @@
-# Picoclaw Launcher TUI
-
-This directory contains the terminal-based TUI launcher for `picoclaw`.
-It provides a lightweight, terminal-native user interface for managing, configuring, and interacting with the core `picoclaw` engine, without requiring a web browser or graphical environment.
-
-## Architecture
-
-The TUI launcher is implemented purely in Go with no external runtime dependencies:
-* **`main.go`**: Application entry point, handles initialization and main event loop
-* **`ui/`**: TUI interface components built on tview + tcell framework:
-  - `home.go`: Main dashboard with navigation menu
-  - `schemes.go`: AI model scheme management
-  - `users.go`: User and API key management for model providers
-  - `channels.go`: Communication channel (Telegram/Discord/WeChat etc.) configuration editor
-  - `gateway.go`: PicoClaw gateway daemon lifecycle management (start/stop/status)
-  - `app.go`: Core TUI application framework and navigation logic
-  - `models.go`: Data structures and state management
-* **`config/`**: Configuration management layer, integrates with the core picoclaw configuration system
-
-## Getting Started
-
-### Prerequisites
-
-* Go 1.25+
-* Terminal with 256-color support (most modern terminals are compatible)
-
-### Development
-
-Run the TUI launcher directly in development mode:
-
-```bash
-# From project root
-go run ./cmd/picoclaw-launcher-tui
-
-# Or from this directory
-go run .
-```
-
-### Build
-
-Build the standalone TUI launcher binary:
-
-```bash
-# From project root (recommended)
-make build-launcher-tui
-
-# Output will be at:
-# build/picoclaw-launcher-tui-<platform>-<arch>
-# with symlink build/picoclaw-launcher-tui
-
-# Or build directly from this directory
-go build -o picoclaw-launcher-tui .
-```
-
-### Key Features
-
-* 🖥️ Terminal-native interface - works over SSH, on headless servers, and in low-resource environments
-* ⚙️ AI model scheme and API key management
-* 📱 Communication channel configuration editor (Telegram/Discord/WeChat etc.)
-* 🔄 PicoClaw gateway daemon management (start/stop/status monitoring)
-* 💬 One-click launch of interactive AI chat session
-* 🎯 Keyboard-first design with intuitive shortcuts
-
-### Other Commands
-
-```bash
-# Run with custom config file path
-go run . /path/to/custom/config.json
-```

cmd/picoclaw-launcher-tui/config/config.go

@@ -1,236 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-// Package config provides types and I/O for ~/.picoclaw/tui.toml.
-package config
-
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-
-	"github.com/BurntSushi/toml"
-
-	"github.com/sipeed/picoclaw/pkg/fileutil"
-)
-
-// DefaultConfigPath returns the default path to the tui.toml config file.
-func DefaultConfigPath() string {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		home = "."
-	}
-	return filepath.Join(home, ".picoclaw", "tui.toml")
-}
-
-// TUIConfig is the top-level structure of ~/.picoclaw/tui.toml.
-type TUIConfig struct {
-	Version  string   `toml:"version"`
-	Model    Model    `toml:"model"`
-	Provider Provider `toml:"provider"`
-}
-
-type Model struct {
-	Type string `toml:"type"` // "provider" (default) | "manual"
-}
-
-type Provider struct {
-	Schemes []Scheme        `toml:"schemes"`
-	Users   []User          `toml:"users"`
-	Current ProviderCurrent `toml:"current"`
-}
-
-type Scheme struct {
-	Name    string `toml:"name"`    // unique key
-	BaseURL string `toml:"baseURL"` // required
-	Type    string `toml:"type"`    // "openai-compatible" (default) | "anthropic"
-}
-
-type User struct {
-	Name   string `toml:"name"`
-	Scheme string `toml:"scheme"` // references Scheme.Name; (Name+Scheme) is unique
-	Type   string `toml:"type"`   // "key" (default) | "OAuth"
-	Key    string `toml:"key"`
-}
-
-type ProviderCurrent struct {
-	Scheme string `toml:"scheme"` // references Scheme.Name
-	User   string `toml:"user"`   // references User.Name where User.Scheme == Scheme
-	Model  string `toml:"model"`  // from GET <baseURL>/models
-}
-
-// DefaultConfig returns a minimal valid TUIConfig.
-func DefaultConfig() *TUIConfig {
-	return &TUIConfig{
-		Version: "1.0",
-		Model:   Model{Type: "provider"},
-		Provider: Provider{
-			Schemes: []Scheme{},
-			Users:   []User{},
-			Current: ProviderCurrent{},
-		},
-	}
-}
-
-// Load reads the TUI config from path. Returns a default config if the file does not exist.
-func Load(path string) (*TUIConfig, error) {
-	data, err := os.ReadFile(path)
-	if os.IsNotExist(err) {
-		return DefaultConfig(), nil
-	}
-	if err != nil {
-		return nil, fmt.Errorf("failed to read config file %q: %w", path, err)
-	}
-
-	cfg := DefaultConfig()
-	if _, err := toml.Decode(string(data), cfg); err != nil {
-		return nil, fmt.Errorf("failed to parse config file %q: %w", path, err)
-	}
-
-	applyDefaults(cfg)
-	return cfg, nil
-}
-
-// Save writes cfg to path atomically (safe for flash / SD storage).
-func Save(path string, cfg *TUIConfig) error {
-	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
-		return fmt.Errorf("failed to create config directory: %w", err)
-	}
-	var buf bytes.Buffer
-	enc := toml.NewEncoder(&buf)
-	if err := enc.Encode(cfg); err != nil {
-		return fmt.Errorf("failed to encode config: %w", err)
-	}
-	if err := fileutil.WriteFileAtomic(path, buf.Bytes(), 0o600); err != nil {
-		return fmt.Errorf("failed to write config file %q: %w", path, err)
-	}
-	return nil
-}
-
-func applyDefaults(cfg *TUIConfig) {
-	if cfg.Version == "" {
-		cfg.Version = "1.0"
-	}
-	if cfg.Model.Type == "" {
-		cfg.Model.Type = "provider"
-	}
-	for i := range cfg.Provider.Schemes {
-		if cfg.Provider.Schemes[i].Type == "" {
-			cfg.Provider.Schemes[i].Type = "openai-compatible"
-		}
-	}
-	for i := range cfg.Provider.Users {
-		if cfg.Provider.Users[i].Type == "" {
-			cfg.Provider.Users[i].Type = "key"
-		}
-	}
-}
-
-// SchemeByName returns the first Scheme whose Name matches, or nil.
-func (p *Provider) SchemeByName(name string) *Scheme {
-	for i := range p.Schemes {
-		if p.Schemes[i].Name == name {
-			return &p.Schemes[i]
-		}
-	}
-	return nil
-}
-
-// UsersForScheme returns all users whose Scheme field matches schemeName.
-func (p *Provider) UsersForScheme(schemeName string) []User {
-	var out []User
-	for _, u := range p.Users {
-		if u.Scheme == schemeName {
-			out = append(out, u)
-		}
-	}
-	return out
-}
-
-// SyncSelectedModelToMainConfig syncs the currently selected model to ~/.picoclaw/config.json
-// Adds/replaces a "tui-prefer" model entry and sets it as the default model.
-// Preserves all other existing fields in the config file unchanged.
-func SyncSelectedModelToMainConfig(scheme Scheme, user User, modelID string) error {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		home = "."
-	}
-	mainConfigPath := filepath.Join(home, ".picoclaw", "config.json")
-
-	var cfg map[string]any
-	if data, readErr := os.ReadFile(mainConfigPath); readErr == nil {
-		if unmarshalErr := json.Unmarshal(data, &cfg); unmarshalErr != nil {
-			cfg = make(map[string]any)
-		}
-	} else {
-		cfg = make(map[string]any)
-	}
-
-	if _, ok := cfg["agents"]; !ok {
-		cfg["agents"] = make(map[string]any)
-	}
-	agents, ok := cfg["agents"].(map[string]any)
-	if ok {
-		if _, ok := agents["defaults"]; !ok {
-			agents["defaults"] = make(map[string]any)
-		}
-		defaults, ok := agents["defaults"].(map[string]any)
-		if ok {
-			defaults["model"] = "tui-prefer"
-		}
-	}
-
-	tuiModel := map[string]any{
-		"model_name": "tui-prefer",
-		"model":      modelID,
-		"api_key":    user.Key,
-		"api_base":   scheme.BaseURL,
-	}
-
-	modelList := []any{}
-	if ml, ok := cfg["model_list"].([]any); ok {
-		modelList = ml
-	}
-
-	found := false
-	for i, m := range modelList {
-		if entry, ok := m.(map[string]any); ok {
-			if name, ok := entry["model_name"].(string); ok && name == "tui-prefer" {
-				modelList[i] = tuiModel
-				found = true
-				break
-			}
-		}
-	}
-	if !found {
-		modelList = append(modelList, tuiModel)
-	}
-	cfg["model_list"] = modelList
-
-	data, err := json.MarshalIndent(cfg, "", "  ")
-	if err != nil {
-		return err
-	}
-
-	if err := os.MkdirAll(filepath.Dir(mainConfigPath), 0o700); err != nil {
-		return err
-	}
-
-	return os.WriteFile(mainConfigPath, data, 0o600)
-}
-
-func (cfg *TUIConfig) CurrentModelLabel() string {
-	cur := cfg.Provider.Current
-	if cur.Model == "" {
-		return "(not configured)"
-	}
-	label := cur.Scheme
-	if label != "" {
-		label += " / "
-	}
-	return label + cur.Model
-}

cmd/picoclaw-launcher-tui/main.go

@@ -1,48 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package main
-
-import (
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/ui"
-)
-
-func main() {
-	configPath := tuicfg.DefaultConfigPath()
-	if len(os.Args) > 1 {
-		configPath = os.Args[1]
-	}
-
-	configDir := filepath.Dir(configPath)
-	if _, err := os.Stat(configDir); os.IsNotExist(err) {
-		cmd := exec.Command("picoclaw", "onboard")
-		cmd.Stdin = os.Stdin
-		cmd.Stdout = os.Stdout
-		cmd.Stderr = os.Stderr
-		_ = cmd.Run()
-	}
-
-	cfg, err := tuicfg.Load(configPath)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
-		os.Exit(1)
-	}
-
-	app := ui.New(cfg, configPath)
-	// Bind model selection hook to sync to main config
-	app.OnModelSelected = func(scheme tuicfg.Scheme, user tuicfg.User, modelID string) {
-		_ = tuicfg.SyncSelectedModelToMainConfig(scheme, user, modelID)
-	}
-	if err := app.Run(); err != nil {
-		fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
-		os.Exit(1)
-	}
-}

cmd/picoclaw-launcher-tui/ui/app.go

@@ -1,325 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-	"sync"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-// App is the root TUI application.
-type App struct {
-	tapp           *tview.Application
-	pages          *tview.Pages
-	pageStack      []string
-	cfg            *tuicfg.TUIConfig
-	configPath     string
-	pageRefreshFns map[string]func()
-	headerModelTV  *tview.TextView
-	modalOpen      map[string]bool
-
-	// OnModelSelected is called when a model is selected in the UI.
-	// Can be nil to disable.
-	OnModelSelected func(scheme tuicfg.Scheme, user tuicfg.User, modelID string)
-
-	modelCache   map[string][]modelEntry
-	modelCacheMu sync.RWMutex
-	refreshMu    sync.Mutex
-}
-
-// cacheKey returns the map key for a (scheme, user) pair.
-func cacheKey(schemeName, userName string) string {
-	return fmt.Sprintf("%s/%s", schemeName, userName)
-}
-
-// cachedModels returns a defensive copy of the cached model list for a user (may be nil).
-func (a *App) cachedModels(schemeName, userName string) []modelEntry {
-	a.modelCacheMu.RLock()
-	defer a.modelCacheMu.RUnlock()
-	entries := a.modelCache[cacheKey(schemeName, userName)]
-	return append([]modelEntry(nil), entries...)
-}
-
-// refreshModelCache fetches models for every user in the config concurrently.
-// Serialized by refreshMu so concurrent calls don't race on the cache map.
-// When all fetches complete it calls onDone via QueueUpdateDraw.
-func (a *App) refreshModelCache(onDone func()) {
-	go func() {
-		a.refreshMu.Lock()
-		defer a.refreshMu.Unlock()
-
-		users := a.cfg.Provider.Users
-		schemes := a.cfg.Provider.Schemes
-
-		schemeURL := make(map[string]string, len(schemes))
-		for _, s := range schemes {
-			schemeURL[s.Name] = s.BaseURL
-		}
-
-		var wg sync.WaitGroup
-		for _, u := range users {
-			baseURL, ok := schemeURL[u.Scheme]
-			if !ok || baseURL == "" {
-				continue
-			}
-			if u.Key == "" {
-				a.modelCacheMu.Lock()
-				if a.modelCache == nil {
-					a.modelCache = make(map[string][]modelEntry)
-				}
-				a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
-				a.modelCacheMu.Unlock()
-				continue
-			}
-			wg.Add(1)
-			bURL := baseURL
-			go func() {
-				defer wg.Done()
-				entries, err := fetchModels(bURL, u.Key)
-				a.modelCacheMu.Lock()
-				if a.modelCache == nil {
-					a.modelCache = make(map[string][]modelEntry)
-				}
-				if err != nil || len(entries) == 0 {
-					a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
-				} else {
-					a.modelCache[cacheKey(u.Scheme, u.Name)] = entries
-				}
-				a.modelCacheMu.Unlock()
-			}()
-		}
-		wg.Wait()
-
-		if onDone != nil {
-			a.tapp.QueueUpdateDraw(onDone)
-		}
-	}()
-}
-
-// New creates and wires up the TUI application.
-func New(cfg *tuicfg.TUIConfig, configPath string) *App {
-	// Cyberpunk Theme Colors
-	// Dark background
-	tview.Styles.PrimitiveBackgroundColor = tcell.NewHexColor(0x050510) // Deep Void
-	tview.Styles.ContrastBackgroundColor = tcell.NewHexColor(0x1a1a2e)  // Dark Indigo
-	tview.Styles.MoreContrastBackgroundColor = tcell.NewHexColor(0x2a2a40)
-
-	// Borders and Titles
-	tview.Styles.BorderColor = tcell.NewHexColor(0x00f0ff)   // Neon Cyan
-	tview.Styles.TitleColor = tcell.NewHexColor(0x00f0ff)    // Neon Cyan
-	tview.Styles.GraphicsColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
-
-	// Text
-	tview.Styles.PrimaryTextColor = tcell.NewHexColor(0xe0e0e0)           // Off-white
-	tview.Styles.SecondaryTextColor = tcell.NewHexColor(0x00f0ff)         // Neon Cyan
-	tview.Styles.TertiaryTextColor = tcell.NewHexColor(0x39ff14)          // Neon Lime
-	tview.Styles.InverseTextColor = tcell.NewHexColor(0x000000)           // Black
-	tview.Styles.ContrastSecondaryTextColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
-
-	a := &App{
-		tapp:           tview.NewApplication(),
-		pages:          tview.NewPages(),
-		pageStack:      []string{},
-		cfg:            cfg,
-		configPath:     configPath,
-		pageRefreshFns: make(map[string]func()),
-		modalOpen:      make(map[string]bool),
-	}
-
-	a.tapp.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			if len(a.modalOpen) > 0 {
-				return event
-			}
-			return a.goBack()
-		}
-		return event
-	})
-
-	a.buildPages()
-	return a
-}
-
-// Run starts the TUI event loop.
-func (a *App) Run() error {
-	return a.tapp.SetRoot(a.pages, true).EnableMouse(true).Run()
-}
-
-func (a *App) buildPages() {
-	a.pages.AddPage("home", a.newHomePage(), true, true)
-	a.pageStack = []string{"home"}
-}
-
-func (a *App) navigateTo(name string, page tview.Primitive) {
-	a.pages.RemovePage(name)
-	a.pages.AddPage(name, page, true, false)
-	a.pageStack = append(a.pageStack, name)
-	a.pages.SwitchToPage(name)
-}
-
-func (a *App) goBack() *tcell.EventKey {
-	if len(a.pageStack) <= 1 {
-		return nil
-	}
-	popped := a.pageStack[len(a.pageStack)-1]
-	a.pageStack = a.pageStack[:len(a.pageStack)-1]
-	a.pages.RemovePage(popped)
-	prev := a.pageStack[len(a.pageStack)-1]
-	if fn, ok := a.pageRefreshFns[prev]; ok {
-		fn()
-	}
-	if prev == "home" && a.headerModelTV != nil {
-		a.headerModelTV.SetText(a.cfg.CurrentModelLabel() + "  ")
-	}
-	a.pages.SwitchToPage(prev)
-	return nil
-}
-
-func (a *App) showModal(name string, primitive tview.Primitive) {
-	a.modalOpen[name] = true
-	a.pages.AddPage(name, primitive, true, true)
-}
-
-func (a *App) hideModal(name string) {
-	delete(a.modalOpen, name)
-	a.pages.HidePage(name)
-	a.pages.RemovePage(name)
-}
-
-func (a *App) save() {
-	if err := tuicfg.Save(a.configPath, a.cfg); err != nil {
-		a.showError("save failed: " + err.Error())
-	}
-}
-
-func (a *App) showError(msg string) {
-	modal := tview.NewModal().
-		SetText(" [red::b]ERROR[-::-]\n\n" + msg).
-		AddButtons([]string{"OK"}).
-		SetDoneFunc(func(_ int, _ string) {
-			a.hideModal("error")
-		})
-	// Cyberpunk Modal Style
-	modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))       // Deep Indigo
-	modal.SetTextColor(tcell.NewHexColor(0xffffff))             // White
-	modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red
-	modal.SetButtonTextColor(tcell.NewHexColor(0xffffff))       // White
-	a.showModal("error", modal)
-}
-
-func (a *App) confirmDelete(label string, onConfirm func()) {
-	modal := tview.NewModal().
-		SetText(" [red::b]DELETE WARNING[-::-]\n\nDelete " + label + "?\n[gray]This action cannot be undone.[-]").
-		AddButtons([]string{"Delete", "Cancel"}).
-		SetDoneFunc(func(_ int, buttonLabel string) {
-			a.hideModal("confirm-delete")
-			if buttonLabel == "Delete" {
-				onConfirm()
-			}
-		})
-	// Cyberpunk Modal Style
-	modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))       // Deep Indigo
-	modal.SetTextColor(tcell.NewHexColor(0xffffff))             // White
-	modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red for danger
-	modal.SetButtonTextColor(tcell.NewHexColor(0xffffff))       // White
-	a.showModal("confirm-delete", modal)
-}
-
-func centeredForm(form *tview.Form, widthPct, height int) tview.Primitive {
-	return tview.NewFlex().
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(tview.NewFlex().SetDirection(tview.FlexRow).
-			AddItem(tview.NewBox(), 0, 1, false).
-			AddItem(form, height, 1, true).
-			AddItem(tview.NewBox(), 0, 1, false), 0, widthPct, true).
-		AddItem(tview.NewBox(), 0, 1, false)
-}
-
-func hintBar(text string) *tview.TextView {
-	tv := tview.NewTextView().
-		SetText(text).
-		SetDynamicColors(true).
-		SetTextAlign(tview.AlignCenter).
-		SetTextColor(tcell.NewHexColor(0x00f0ff)) // Neon Cyan
-	tv.SetBackgroundColor(tcell.NewHexColor(0x2a2a40)) // Darker Indigo
-	return tv
-}
-
-func (a *App) buildShell(pageID string, content tview.Primitive, hint string) tview.Primitive {
-	var modelTV *tview.TextView
-	if pageID == "home" {
-		if a.headerModelTV == nil {
-			a.headerModelTV = tview.NewTextView()
-			a.headerModelTV.SetTextAlign(tview.AlignRight).
-				SetTextColor(tcell.NewHexColor(0x39ff14)). // Neon Lime
-				SetDynamicColors(true).
-				SetBackgroundColor(tcell.NewHexColor(0x050510))
-		}
-		modelTV = a.headerModelTV
-		modelTV.SetText("MODEL: " + a.cfg.CurrentModelLabel() + " ")
-	} else {
-		modelTV = tview.NewTextView()
-		modelTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
-	}
-
-	headerLeft := tview.NewTextView().
-		SetText(" [#ff00ff::b]///[#00f0ff] PICOCLAW LAUNCHER [#ff00ff]///").
-		SetDynamicColors(true).
-		SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	header := tview.NewFlex().
-		AddItem(headerLeft, 0, 1, false).
-		AddItem(modelTV, 0, 1, false)
-
-	sidebar := tview.NewTextView().
-		SetDynamicColors(true).
-		SetWrap(false)
-	sidebar.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e)) // Deep Indigo
-
-	// Cyberpunk Sidebar Styling
-	activePrefix := "[#39ff14::b]>> " // Neon Lime arrow
-	activeSuffix := "[-]"
-	inactivePrefix := "[#808080]   "
-	inactiveSuffix := "[-]"
-
-	sbText := "\n\n" // Top padding
-
-	menuItem := func(id, label string) string {
-		if pageID == id {
-			return activePrefix + label + activeSuffix + "\n\n"
-		}
-		return inactivePrefix + label + inactiveSuffix + "\n\n"
-	}
-
-	sbText += menuItem("home", "HOME")
-	sbText += menuItem("schemes", "SCHEMES")
-	sbText += menuItem("users", "USERS")
-	sbText += menuItem("models", "MODELS")
-	sbText += menuItem("channels", "CHANNELS")
-	sbText += menuItem("gateway", "GATEWAY")
-
-	sidebar.SetText(sbText)
-
-	footer := hintBar(hint)
-
-	grid := tview.NewGrid().
-		SetRows(1, 0, 1).
-		SetColumns(20, 0). // Slightly wider sidebar
-		AddItem(header, 0, 0, 1, 2, 0, 0, false).
-		AddItem(sidebar, 1, 0, 1, 1, 0, 0, false).
-		AddItem(content, 1, 1, 1, 1, 0, 0, true).
-		AddItem(footer, 2, 0, 1, 2, 0, 0, false)
-
-	// Add a border around the content area if possible, or ensure content has its own border
-	// grid.SetBorders(false) // Grid borders usually look bad, handled by components
-
-	return grid
-}

cmd/picoclaw-launcher-tui/ui/channels.go

@@ -1,202 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-	"reflect"
-	"strconv"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-)
-
-func (a *App) newChannelsPage() tview.Primitive {
-	list := tview.NewList()
-	list.SetBorder(true).
-		SetTitle(" [#00f0ff::b] COMMUNICATION CHANNELS ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
-	list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
-	list.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0x050510)),
-	)
-	list.SetHighlightFullLine(true)
-	list.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	rebuild := func() {
-		sel := list.GetCurrentItem()
-		list.Clear()
-
-		home, err := os.UserHomeDir()
-		if err != nil {
-			home = "."
-		}
-		configPath := filepath.Join(home, ".picoclaw", "config.json")
-
-		var cfg map[string]any
-		if data, err := os.ReadFile(configPath); err == nil {
-			_ = json.Unmarshal(data, &cfg)
-		}
-
-		if chRaw, ok := cfg["channels"].(map[string]any); ok {
-			for name, ch := range chRaw {
-				chMap, ok := ch.(map[string]any)
-				enabled := "disabled"
-				if ok {
-					if e, ok := chMap["enabled"].(bool); ok && e {
-						enabled = "enabled"
-					}
-				}
-				list.AddItem(name, fmt.Sprintf("Status: %s", enabled), 0, func() {
-					a.showChannelEditForm(configPath, name, chMap)
-				})
-			}
-		}
-
-		if sel >= 0 && sel < list.GetItemCount() {
-			list.SetCurrentItem(sel)
-		}
-	}
-	rebuild()
-
-	a.pageRefreshFns["channels"] = rebuild
-
-	list.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			return a.goBack()
-		}
-		return event
-	})
-
-	return a.buildShell("channels", list, " [#ff00ff]Enter:[-] edit  [#ff2a2a]ESC:[-] back ")
-}
-
-func (a *App) showChannelEditForm(configPath, channelName string, existing map[string]any) {
-	form := tview.NewForm()
-	form.SetBorder(true).
-		SetTitle(" [::b]EDIT CHANNEL ").
-		SetTitleColor(tcell.NewHexColor(0x39ff14)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
-	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
-	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
-	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
-	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
-	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
-
-	fields := make(map[string]*tview.InputField)
-	var nameField *tview.InputField
-
-	if channelName == "" {
-		nameField = tview.NewInputField().
-			SetLabel("Channel Name").
-			SetText("").
-			SetFieldWidth(28)
-		form.AddFormItem(nameField)
-	}
-
-	for k, v := range existing {
-		if reflect.ValueOf(v).Kind() == reflect.Map || reflect.ValueOf(v).Kind() == reflect.Slice {
-			continue
-		}
-		valStr := fmt.Sprintf("%v", v)
-		field := tview.NewInputField().
-			SetLabel(k).
-			SetText(valStr).
-			SetFieldWidth(28)
-		form.AddFormItem(field)
-		fields[k] = field
-	}
-
-	form.AddButton("SAVE", func() {
-		var cfg map[string]any
-		if data, err := os.ReadFile(configPath); err == nil {
-			if err := json.Unmarshal(data, &cfg); err != nil {
-				cfg = make(map[string]any)
-			}
-		} else {
-			cfg = make(map[string]any)
-		}
-
-		if _, ok := cfg["channels"]; !ok {
-			cfg["channels"] = make(map[string]any)
-		}
-		channels, ok := cfg["channels"].(map[string]any)
-		if !ok {
-			channels = make(map[string]any)
-			cfg["channels"] = channels
-		}
-
-		finalName := channelName
-		if channelName == "" {
-			if nameField == nil || nameField.GetText() == "" {
-				a.showError("Channel name is required")
-				return
-			}
-			finalName = nameField.GetText()
-		}
-
-		updated := make(map[string]any)
-		if existing != nil {
-			for k, v := range existing {
-				updated[k] = v
-			}
-		}
-		for k, field := range fields {
-			val := field.GetText()
-			if val == "true" {
-				updated[k] = true
-			} else if val == "false" {
-				updated[k] = false
-			} else if num, err := strconv.Atoi(val); err == nil {
-				updated[k] = num
-			} else {
-				updated[k] = val
-			}
-		}
-
-		if channelName != "" && finalName != channelName {
-			delete(channels, channelName)
-		}
-		channels[finalName] = updated
-
-		data, err := json.MarshalIndent(cfg, "", "  ")
-		if err != nil {
-			a.showError(fmt.Sprintf("Failed to save config: %v", err))
-			return
-		}
-		if err := os.MkdirAll(filepath.Dir(configPath), 0o700); err != nil {
-			a.showError(fmt.Sprintf("Failed to create config directory: %v", err))
-			return
-		}
-		if err := os.WriteFile(configPath, data, 0o600); err != nil {
-			a.showError(fmt.Sprintf("Failed to write config: %v", err))
-			return
-		}
-
-		a.hideModal("channel-edit")
-		a.goBack()
-	})
-
-	form.AddButton("CANCEL", func() {
-		a.hideModal("channel-edit")
-	})
-
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			a.hideModal("channel-edit")
-			return nil
-		}
-		return event
-	})
-
-	a.showModal("channel-edit", centeredForm(form, 4, 20))
-}

cmd/picoclaw-launcher-tui/ui/gateway.go

@@ -1,229 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-	"os/exec"
-	"runtime"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-	ppid "github.com/sipeed/picoclaw/pkg/pid"
-)
-
-type gatewayStatus struct {
-	running bool
-	pid     int
-	version string
-}
-
-func picoHome() string {
-	return config.GetHome()
-}
-
-func getGatewayStatus() gatewayStatus {
-	data := ppid.ReadPidFileWithCheck(picoHome())
-	if data == nil {
-		return gatewayStatus{running: false}
-	}
-	return gatewayStatus{
-		running: true,
-		pid:     data.PID,
-		version: data.Version,
-	}
-}
-
-func startGateway() error {
-	status := getGatewayStatus()
-	if status.running {
-		return fmt.Errorf("gateway is already running (PID: %d)", status.pid)
-	}
-
-	var cmd *exec.Cmd
-
-	if runtime.GOOS == "windows" {
-		cmd = exec.Command("cmd", "/C", "start /B picoclaw gateway > NUL 2>&1")
-	} else {
-		cmd = exec.Command("sh", "-c", "nohup picoclaw gateway > /dev/null 2>&1 &")
-	}
-
-	err := cmd.Start()
-	if err != nil {
-		return err
-	}
-
-	time.Sleep(1 * time.Second)
-
-	if runtime.GOOS == "windows" {
-		cmd := exec.Command(
-			"wmic",
-			"process",
-			"where",
-			"name='picoclaw.exe' and commandline like '%gateway%'",
-			"get",
-			"processid",
-		)
-		output, err := cmd.Output()
-		if err != nil {
-			return fmt.Errorf("failed to get gateway PID: %w", err)
-		}
-		lines := strings.Split(string(output), "\n")
-		for _, line := range lines[1:] {
-			line = strings.TrimSpace(line)
-			if line == "" {
-				continue
-			}
-			_, err := strconv.Atoi(line)
-			if err == nil {
-				break
-			}
-		}
-	}
-
-	status = getGatewayStatus()
-	if !status.running {
-		return fmt.Errorf("failed to start gateway")
-	}
-	return nil
-}
-
-func stopGateway() error {
-	status := getGatewayStatus()
-	if !status.running {
-		return fmt.Errorf("gateway is not running")
-	}
-
-	var err error
-	if runtime.GOOS == "windows" {
-		err = exec.Command("taskkill", "/F", "/PID", strconv.Itoa(status.pid)).Run()
-	} else {
-		err = exec.Command("kill", strconv.Itoa(status.pid)).Run()
-	}
-	if err != nil {
-		return err
-	}
-
-	// Wait for process to stop (ReadPidFileWithCheck cleans up stale pid file)
-	for i := 0; i < 5; i++ {
-		if !getGatewayStatus().running {
-			break
-		}
-		time.Sleep(200 * time.Millisecond)
-	}
-
-	return nil
-}
-
-func (a *App) newGatewayPage() tview.Primitive {
-	flex := tview.NewFlex().SetDirection(tview.FlexRow)
-	flex.SetBorder(true).
-		SetTitle(" [#00f0ff::b] GATEWAY MANAGEMENT ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	flex.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	statusTV := tview.NewTextView().
-		SetDynamicColors(true).
-		SetTextAlign(tview.AlignCenter).
-		SetText("Checking status...")
-	statusTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	var updateStatus func()
-
-	// 使用List作为按钮，保证显示和交互正常
-	buttons := tview.NewList()
-	buttons.SetBackgroundColor(tcell.NewHexColor(0x050510))
-	buttons.SetMainTextColor(tcell.ColorWhite)
-	buttons.SetSelectedBackgroundColor(tcell.NewHexColor(0xff00ff))
-	buttons.SetSelectedTextColor(tcell.ColorBlack)
-
-	buttons.AddItem(" [lime]START[white]   ", "", 0, func() {
-		if !getGatewayStatus().running {
-			err := startGateway()
-			if err != nil {
-				a.showError(err.Error())
-			}
-			updateStatus()
-		}
-	})
-	buttons.AddItem(" [red]STOP[white]    ", "", 0, func() {
-		if getGatewayStatus().running {
-			err := stopGateway()
-			if err != nil {
-				a.showError(err.Error())
-			}
-			updateStatus()
-		}
-	})
-
-	buttonFlex := tview.NewFlex().SetDirection(tview.FlexColumn)
-	buttonFlex.
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(buttons, 20, 1, true).
-		AddItem(tview.NewBox(), 0, 1, false)
-
-	flex.
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(statusTV, 3, 1, false).
-		AddItem(tview.NewBox(), 0, 1, false).
-		AddItem(buttonFlex, 4, 1, true).
-		AddItem(tview.NewBox(), 0, 1, false)
-
-	updateStatus = func() {
-		status := getGatewayStatus()
-		if status.running {
-			versionInfo := ""
-			if status.version != "" {
-				versionInfo = fmt.Sprintf("\nVersion: %s", status.version)
-			}
-			statusTV.SetText(fmt.Sprintf("[#39ff14::b]GATEWAY RUNNING[-]\n\nPID: %d%s", status.pid, versionInfo))
-			buttons.SetItemText(0, " [gray]START[white]   ", "")
-			buttons.SetItemText(1, " [red]STOP[white]    ", "")
-		} else {
-			statusTV.SetText("[#ff2a2a::b]GATEWAY STOPPED[-]\n\nPID: N/A")
-			buttons.SetItemText(0, " [lime]START[white]   ", "")
-			buttons.SetItemText(1, " [gray]STOP[white]    ", "")
-		}
-	}
-
-	updateStatus()
-
-	done := make(chan struct{})
-	go func() {
-		ticker := time.NewTicker(2 * time.Second)
-		defer ticker.Stop()
-		for {
-			select {
-			case <-ticker.C:
-				a.tapp.QueueUpdateDraw(updateStatus)
-			case <-done:
-				return
-			}
-		}
-	}()
-
-	originalInputCapture := flex.GetInputCapture()
-	flex.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			close(done)
-			return a.goBack()
-		}
-		if originalInputCapture != nil {
-			return originalInputCapture(event)
-		}
-		return event
-	})
-
-	a.pageRefreshFns["gateway"] = updateStatus
-
-	return a.buildShell("gateway", flex, " [#39ff14]Enter:[-] select  [#ff2a2a]ESC:[-] back ")
-}

cmd/picoclaw-launcher-tui/ui/home.go

@@ -1,70 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"os"
-	"os/exec"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-)
-
-func (a *App) newHomePage() tview.Primitive {
-	list := tview.NewList()
-	list.SetBorder(true).
-		SetTitle(" [#00f0ff::b] ACTIVE CONFIGURATION ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
-	list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
-	list.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0x39ff14)).Foreground(tcell.NewHexColor(0x050510)),
-	)
-	list.SetHighlightFullLine(true)
-	list.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	rebuildList := func() {
-		sel := list.GetCurrentItem()
-		list.Clear()
-		list.AddItem("MODEL: "+a.cfg.CurrentModelLabel(), "Select to configure AI model", 'm', func() {
-			a.navigateTo("schemes", a.newSchemesPage())
-		})
-		list.AddItem(
-			"CHANNELS: Configure communication channels",
-			"Manage Telegram/Discord/WeChat channels",
-			'n',
-			func() {
-				a.navigateTo("channels", a.newChannelsPage())
-			},
-		)
-		list.AddItem("GATEWAY MANAGEMENT", "Manage PicoClaw gateway daemon", 'g', func() {
-			a.navigateTo("gateway", a.newGatewayPage())
-		})
-		list.AddItem("CHAT: Start AI agent chat", "Launch interactive chat session", 'c', func() {
-			a.tapp.Suspend(func() {
-				cmd := exec.Command("picoclaw", "agent")
-				cmd.Stdin = os.Stdin
-				cmd.Stdout = os.Stdout
-				cmd.Stderr = os.Stderr
-				_ = cmd.Run()
-			})
-		})
-		list.AddItem("QUIT SYSTEM", "Exit PicoClaw Launcher", 'q', func() { a.tapp.Stop() })
-		if sel >= 0 && sel < list.GetItemCount() {
-			list.SetCurrentItem(sel)
-		}
-	}
-	rebuildList()
-
-	a.pageRefreshFns["home"] = rebuildList
-
-	return a.buildShell(
-		"home",
-		list,
-		" [#00f0ff]m:[-] model  [#00f0ff]n:[-] channels  [#00f0ff]g:[-] gateway  [#00f0ff]c:[-] chat  [#ff2a2a]q:[-] quit ",
-	)
-}

cmd/picoclaw-launcher-tui/ui/models.go

@@ -1,200 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-type modelsAPIResponse struct {
-	Data []modelEntry `json:"data"`
-}
-
-type modelEntry struct {
-	ID          string `json:"id"`
-	Name        string `json:"name"`
-	Description string `json:"description"`
-}
-
-func (a *App) newModelsPage(schemeName, userName, baseURL string) tview.Primitive {
-	table := tview.NewTable().
-		SetBorders(false).
-		SetSelectable(true, false).
-		SetFixed(0, 0)
-	table.SetBorder(true).
-		SetTitle(fmt.Sprintf(" [#00f0ff::b] MODELS · %s / %s ", schemeName, userName)).
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	table.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
-	)
-	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	var modelIDs []string
-
-	status := tview.NewTextView().
-		SetTextAlign(tview.AlignCenter).
-		SetDynamicColors(true).
-		SetText("[#ffff00]FETCHING MODELS...[-]")
-	status.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	flex := tview.NewFlex().
-		SetDirection(tview.FlexRow).
-		AddItem(status, 1, 0, false).
-		AddItem(table, 0, 1, false)
-
-	apiKey := a.resolveKey(schemeName, userName)
-
-	go func() {
-		var entries []modelEntry
-		var err error
-		if apiKey == "" {
-			err = fmt.Errorf("key is required")
-		} else {
-			entries, err = fetchModels(baseURL, apiKey)
-		}
-
-		a.modelCacheMu.Lock()
-		if a.modelCache == nil {
-			a.modelCache = make(map[string][]modelEntry)
-		}
-		if err == nil && len(entries) > 0 {
-			a.modelCache[cacheKey(schemeName, userName)] = entries
-		} else {
-			a.modelCache[cacheKey(schemeName, userName)] = nil
-		}
-		a.modelCacheMu.Unlock()
-
-		a.tapp.QueueUpdateDraw(func() {
-			if err != nil {
-				status.SetText(fmt.Sprintf("[#ff2a2a]ERROR: %s[-]", err.Error()))
-				table.SetCell(0, 0, tview.NewTableCell(" (failed to load models)"))
-				a.tapp.SetFocus(table)
-				return
-			}
-			if len(entries) == 0 {
-				status.SetText("[#ff2a2a]NO MODELS RETURNED[-]")
-				table.SetCell(0, 0, tview.NewTableCell(" (no models available)"))
-				a.tapp.SetFocus(table)
-				return
-			}
-
-			status.SetText(fmt.Sprintf("[#39ff14]%d MODEL(S) LOADED[-]", len(entries)))
-			for i, m := range entries {
-				modelIDs = append(modelIDs, m.ID)
-				table.SetCell(i, 0,
-					tview.NewTableCell(fmt.Sprintf("%3d", i+1)).
-						SetAlign(tview.AlignRight).
-						SetTextColor(tcell.NewHexColor(0x808080)).
-						SetSelectable(false),
-				)
-				table.SetCell(i, 1,
-					tview.NewTableCell(" "+m.ID).
-						SetAlign(tview.AlignLeft).
-						SetExpansion(1).
-						SetTextColor(tcell.NewHexColor(0xe0e0e0)),
-				)
-			}
-			a.tapp.SetFocus(table)
-		})
-	}()
-
-	table.SetSelectedFunc(func(row, _ int) {
-		if row < 0 || row >= len(modelIDs) {
-			return
-		}
-		a.cfg.Provider.Current = tuicfg.ProviderCurrent{
-			Scheme: schemeName,
-			User:   userName,
-			Model:  modelIDs[row],
-		}
-		a.save()
-
-		// Trigger model selected callback if set
-		if a.OnModelSelected != nil && a.cfg.Model.Type == "provider" {
-			scheme := a.cfg.Provider.SchemeByName(schemeName)
-			if scheme == nil {
-				a.goBack()
-				return
-			}
-			var user tuicfg.User
-			for _, u := range a.cfg.Provider.Users {
-				if u.Scheme == schemeName && u.Name == userName {
-					user = u
-					break
-				}
-			}
-			a.OnModelSelected(*scheme, user, modelIDs[row])
-		}
-
-		a.goBack()
-	})
-
-	return a.buildShell("models", flex, " [#39ff14]Enter:[-] select  [#ff00ff]ESC:[-] back ")
-}
-
-func (a *App) resolveKey(schemeName, userName string) string {
-	for _, u := range a.cfg.Provider.Users {
-		if u.Scheme == schemeName && u.Name == userName {
-			return u.Key
-		}
-	}
-	return ""
-}
-
-func fetchModels(baseURL, apiKey string) ([]modelEntry, error) {
-	url := strings.TrimRight(baseURL, "/") + "/models"
-
-	client := &http.Client{Timeout: 15 * time.Second}
-	req, err := http.NewRequest(http.MethodGet, url, nil)
-	if err != nil {
-		return nil, fmt.Errorf("build request: %w", err)
-	}
-	if apiKey != "" {
-		req.Header.Set("Authorization", "Bearer "+apiKey)
-	}
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
-		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, fmt.Errorf("read response: %w", err)
-	}
-
-	var result modelsAPIResponse
-	if err := json.Unmarshal(body, &result); err == nil && len(result.Data) > 0 {
-		return result.Data, nil
-	}
-
-	var arr []modelEntry
-	if err := json.Unmarshal(body, &arr); err == nil {
-		return arr, nil
-	}
-
-	return nil, fmt.Errorf(
-		"decode response: unrecognized shape: %s",
-		strings.TrimSpace(string(body[:min(len(body), 256)])),
-	)
-}

cmd/picoclaw-launcher-tui/ui/schemes.go

@@ -1,252 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-func (a *App) newSchemesPage() tview.Primitive {
-	table := tview.NewTable().
-		SetBorders(false).
-		SetSelectable(true, false)
-	table.SetBorder(true).
-		SetTitle(" [#00f0ff::b] PROVIDER SCHEMES ").
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	table.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
-	)
-	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	rowToIdx := func(row int) int { return row / 2 }
-
-	selectedSchemeName := func() string {
-		row, _ := table.GetSelection()
-		idx := rowToIdx(row)
-		schemes := a.cfg.Provider.Schemes
-		if idx >= 0 && idx < len(schemes) {
-			return schemes[idx].Name
-		}
-		return ""
-	}
-
-	rebuild := func() {
-		selName := selectedSchemeName()
-		table.Clear()
-		schemes := a.cfg.Provider.Schemes
-		for i, s := range schemes {
-			nameRow := i * 2
-			detailRow := nameRow + 1
-
-			table.SetCell(nameRow, 0,
-				tview.NewTableCell(" "+s.Name).
-					SetTextColor(tcell.NewHexColor(0xe0e0e0)).
-					SetExpansion(1).
-					SetSelectable(true),
-			)
-
-			users := a.cfg.Provider.UsersForScheme(s.Name)
-			n := len(users)
-			m := 0
-			for _, u := range users {
-				if models := a.cachedModels(s.Name, u.Name); len(models) > 0 {
-					m++
-				}
-			}
-			table.SetCell(detailRow, 0,
-				tview.NewTableCell(fmt.Sprintf("  [#808080](%d/%d) %s", m, n, s.BaseURL)).
-					SetTextColor(tcell.NewHexColor(0x808080)).
-					SetExpansion(1).
-					SetSelectable(false),
-			)
-			table.SetCell(detailRow, 1,
-				tview.NewTableCell("[#00f0ff]"+s.Type+"  ").
-					SetAlign(tview.AlignRight).
-					SetSelectable(false),
-			)
-		}
-		if selName != "" {
-			for i, s := range schemes {
-				if s.Name == selName {
-					table.Select(i*2, 0)
-					return
-				}
-			}
-		}
-		if table.GetRowCount() > 0 {
-			table.Select(0, 0)
-		}
-	}
-	rebuild()
-
-	a.refreshModelCache(rebuild)
-	a.pageRefreshFns["schemes"] = func() { a.refreshModelCache(rebuild) }
-
-	table.SetSelectedFunc(func(row, _ int) {
-		idx := rowToIdx(row)
-		schemes := a.cfg.Provider.Schemes
-		if idx < 0 || idx >= len(schemes) {
-			return
-		}
-		name := schemes[idx].Name
-		a.navigateTo("users", a.newUsersPage(name))
-	})
-
-	table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		row, _ := table.GetSelection()
-		idx := rowToIdx(row)
-		schemes := a.cfg.Provider.Schemes
-		switch event.Rune() {
-		case 'a':
-			a.showSchemeForm(nil, func(s tuicfg.Scheme) {
-				a.cfg.Provider.Schemes = append(a.cfg.Provider.Schemes, s)
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		case 'e':
-			if idx < 0 || idx >= len(schemes) {
-				return nil
-			}
-			origName := schemes[idx].Name
-			orig := schemes[idx]
-			a.showSchemeForm(&orig, func(s tuicfg.Scheme) {
-				current := a.cfg.Provider.Schemes
-				for i, sc := range current {
-					if sc.Name == origName {
-						a.cfg.Provider.Schemes[i] = s
-						break
-					}
-				}
-				a.save()
-				a.refreshModelCache(func() {
-					rebuild()
-					for i, sc := range a.cfg.Provider.Schemes {
-						if sc.Name == s.Name {
-							table.Select(i*2, 0)
-							break
-						}
-					}
-				})
-			})
-			return nil
-		case 'd':
-			if idx < 0 || idx >= len(schemes) {
-				return nil
-			}
-			name := schemes[idx].Name
-			a.confirmDelete(fmt.Sprintf("scheme %q", name), func() {
-				current := a.cfg.Provider.Schemes
-				newSchemes := make([]tuicfg.Scheme, 0, len(current))
-				for _, sc := range current {
-					if sc.Name != name {
-						newSchemes = append(newSchemes, sc)
-					}
-				}
-				a.cfg.Provider.Schemes = newSchemes
-
-				existing := a.cfg.Provider.Users
-				filtered := make([]tuicfg.User, 0, len(existing))
-				for _, u := range existing {
-					if u.Scheme != name {
-						filtered = append(filtered, u)
-					}
-				}
-				a.cfg.Provider.Users = filtered
-
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		}
-		return event
-	})
-
-	return a.buildShell(
-		"schemes",
-		table,
-		" [#00f0ff]a:[-] add  [#00f0ff]e:[-] edit  [#ff2a2a]d:[-] delete  [#39ff14]Enter:[-] open  [#ff00ff]ESC:[-] back ",
-	)
-}
-
-func (a *App) showSchemeForm(existing *tuicfg.Scheme, onSave func(tuicfg.Scheme)) {
-	name := ""
-	baseURL := ""
-	schemeType := "openai-compatible"
-	title := " ADD SCHEME "
-
-	if existing != nil {
-		name = existing.Name
-		baseURL = existing.BaseURL
-		schemeType = existing.Type
-		title = " EDIT SCHEME "
-	}
-
-	typeOptions := []string{"openai-compatible", "anthropic"}
-	typeIdx := 0
-	for i, t := range typeOptions {
-		if t == schemeType {
-			typeIdx = i
-			break
-		}
-	}
-
-	form := tview.NewForm()
-
-	form.
-		AddInputField("Name", name, 20, nil, func(text string) { name = text }).
-		AddInputField("Base URL", baseURL, 28, nil, func(text string) { baseURL = text }).
-		AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { schemeType = option }).
-		AddButton("SAVE", func() {
-			if name == "" {
-				a.showError("Name is required")
-				return
-			}
-			if baseURL == "" {
-				a.showError("Base URL is required")
-				return
-			}
-			if existing == nil {
-				for _, s := range a.cfg.Provider.Schemes {
-					if s.Name == name {
-						a.showError(fmt.Sprintf("Scheme name %q already exists", name))
-						return
-					}
-				}
-			}
-			a.hideModal("scheme-form")
-			onSave(tuicfg.Scheme{Name: name, BaseURL: baseURL, Type: schemeType})
-		}).
-		AddButton("CANCEL", func() {
-			a.hideModal("scheme-form")
-		})
-
-	form.SetBorder(true).
-		SetTitle(" [::b]" + title + " ").
-		SetTitleColor(tcell.NewHexColor(0x39ff14)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
-	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
-	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
-	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
-	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
-	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			a.hideModal("scheme-form")
-			return nil
-		}
-		return event
-	})
-
-	a.showModal("scheme-form", centeredForm(form, 4, 12))
-}

cmd/picoclaw-launcher-tui/ui/users.go

@@ -1,261 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-//
-// Copyright (c) 2026 PicoClaw contributors
-
-package ui
-
-import (
-	"fmt"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
-)
-
-func (a *App) newUsersPage(schemeName string) tview.Primitive {
-	table := tview.NewTable().
-		SetBorders(false).
-		SetSelectable(true, false)
-	table.SetBorder(true).
-		SetTitle(fmt.Sprintf(" [#00f0ff::b] USERS · %s ", schemeName)).
-		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	table.SetSelectedStyle(
-		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
-	)
-	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
-
-	visibleUsers := func() []tuicfg.User {
-		var out []tuicfg.User
-		for _, u := range a.cfg.Provider.Users {
-			if u.Scheme == schemeName {
-				out = append(out, u)
-			}
-		}
-		return out
-	}
-
-	findUserGlobalIdx := func(userName string) int {
-		for i, u := range a.cfg.Provider.Users {
-			if u.Scheme == schemeName && u.Name == userName {
-				return i
-			}
-		}
-		return -1
-	}
-
-	rowToVisIdx := func(row int) int { return row / 2 }
-
-	selectedUserName := func() string {
-		row, _ := table.GetSelection()
-		users := visibleUsers()
-		visIdx := rowToVisIdx(row)
-		if visIdx >= 0 && visIdx < len(users) {
-			return users[visIdx].Name
-		}
-		return ""
-	}
-
-	rebuild := func() {
-		selName := selectedUserName()
-		table.Clear()
-		users := visibleUsers()
-		for i, u := range users {
-			nameRow := i * 2
-			detailRow := nameRow + 1
-
-			table.SetCell(nameRow, 0,
-				tview.NewTableCell(" "+u.Name).
-					SetTextColor(tcell.NewHexColor(0xe0e0e0)).
-					SetExpansion(1).
-					SetSelectable(true),
-			)
-			table.SetCell(nameRow, 1,
-				tview.NewTableCell("").
-					SetSelectable(false),
-			)
-
-			models := a.cachedModels(schemeName, u.Name)
-			var detailText string
-			if len(models) > 0 {
-				detailText = fmt.Sprintf("  [#39ff14]%d models available[-]", len(models))
-			} else {
-				detailText = "  [#ff2a2a]Inactive / No Access[-]"
-			}
-			table.SetCell(detailRow, 0,
-				tview.NewTableCell(detailText).
-					SetTextColor(tcell.NewHexColor(0x808080)).
-					SetExpansion(1).
-					SetSelectable(false),
-			)
-			table.SetCell(detailRow, 1,
-				tview.NewTableCell("[#00f0ff]"+u.Type+"  ").
-					SetAlign(tview.AlignRight).
-					SetSelectable(false),
-			)
-		}
-		if selName != "" {
-			for i, u := range users {
-				if u.Name == selName {
-					table.Select(i*2, 0)
-					return
-				}
-			}
-		}
-		if table.GetRowCount() > 0 {
-			table.Select(0, 0)
-		}
-	}
-	rebuild()
-
-	a.refreshModelCache(rebuild)
-	a.pageRefreshFns["users"] = func() { a.refreshModelCache(rebuild) }
-
-	table.SetSelectedFunc(func(row, _ int) {
-		visIdx := rowToVisIdx(row)
-		users := visibleUsers()
-		if visIdx < 0 || visIdx >= len(users) {
-			return
-		}
-		uName := users[visIdx].Name
-		scheme := a.cfg.Provider.SchemeByName(schemeName)
-		if scheme == nil {
-			a.showError(fmt.Sprintf("Scheme %q not found", schemeName))
-			return
-		}
-		a.navigateTo("models", a.newModelsPage(schemeName, uName, scheme.BaseURL))
-	})
-
-	table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		row, _ := table.GetSelection()
-		visIdx := rowToVisIdx(row)
-		users := visibleUsers()
-		switch event.Rune() {
-		case 'a':
-			a.showUserForm(schemeName, nil, func(u tuicfg.User) {
-				a.cfg.Provider.Users = append(a.cfg.Provider.Users, u)
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		case 'e':
-			if visIdx < 0 || visIdx >= len(users) {
-				return nil
-			}
-			origName := users[visIdx].Name
-			orig := a.cfg.Provider.Users[findUserGlobalIdx(origName)]
-			a.showUserForm(schemeName, &orig, func(u tuicfg.User) {
-				cfgIdx := findUserGlobalIdx(origName)
-				if cfgIdx < 0 {
-					a.showError(fmt.Sprintf("User %q no longer exists", origName))
-					return
-				}
-				a.cfg.Provider.Users[cfgIdx] = u
-				a.save()
-				a.refreshModelCache(func() {
-					rebuild()
-					for i, usr := range visibleUsers() {
-						if usr.Name == u.Name {
-							table.Select(i*2, 0)
-							break
-						}
-					}
-				})
-			})
-			return nil
-		case 'd':
-			if visIdx < 0 || visIdx >= len(users) {
-				return nil
-			}
-			uName := users[visIdx].Name
-			a.confirmDelete(fmt.Sprintf("user %q", uName), func() {
-				cfgIdx := findUserGlobalIdx(uName)
-				if cfgIdx < 0 {
-					return
-				}
-				all := a.cfg.Provider.Users
-				a.cfg.Provider.Users = append(all[:cfgIdx], all[cfgIdx+1:]...)
-				a.save()
-				a.refreshModelCache(rebuild)
-			})
-			return nil
-		}
-		return event
-	})
-
-	return a.buildShell(
-		"users",
-		table,
-		" [#00f0ff]a:[-] add  [#00f0ff]e:[-] edit  [#ff2a2a]d:[-] delete  [#39ff14]Enter:[-] models  [#ff00ff]ESC:[-] back ",
-	)
-}
-
-func (a *App) showUserForm(schemeName string, existing *tuicfg.User, onSave func(tuicfg.User)) {
-	name := ""
-	userType := "key"
-	key := ""
-	title := " ADD USER "
-
-	if existing != nil {
-		name = existing.Name
-		userType = existing.Type
-		key = existing.Key
-		title = " EDIT USER "
-	}
-
-	typeOptions := []string{"key", "OAuth"}
-	typeIdx := 0
-	for i, t := range typeOptions {
-		if t == userType {
-			typeIdx = i
-			break
-		}
-	}
-
-	form := tview.NewForm()
-	form.
-		AddInputField("Name", name, 20, nil, func(text string) { name = text }).
-		AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { userType = option }).
-		AddPasswordField("Key", key, 28, '*', func(text string) { key = text }).
-		AddButton("SAVE", func() {
-			if name == "" {
-				a.showError("Name is required")
-				return
-			}
-			if existing == nil {
-				for _, u := range a.cfg.Provider.Users {
-					if u.Scheme == schemeName && u.Name == name {
-						a.showError(fmt.Sprintf("User name %q already exists for this scheme", name))
-						return
-					}
-				}
-			}
-			a.hideModal("user-form")
-			onSave(tuicfg.User{Name: name, Scheme: schemeName, Type: userType, Key: key})
-		}).
-		AddButton("CANCEL", func() {
-			a.hideModal("user-form")
-		})
-
-	form.SetBorder(true).
-		SetTitle(" [::b]" + title + " ").
-		SetTitleColor(tcell.NewHexColor(0x39ff14)).
-		SetBorderColor(tcell.NewHexColor(0x00f0ff))
-	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
-	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
-	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
-	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
-	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
-	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEscape {
-			a.hideModal("user-form")
-			return nil
-		}
-		return event
-	})
-
-	a.showModal("user-form", centeredForm(form, 4, 13))
-}

cmd/picoclaw/internal/cliui/mcp_show.go

@@ -0,0 +1,384 @@
+package cliui
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/charmbracelet/lipgloss"
+)
+
+// MCPShowServer holds the server metadata for PrintMCPShow.
+type MCPShowServer struct {
+	Name              string
+	Type              string
+	Target            string
+	Enabled           bool
+	EffectiveDeferred bool     // resolved value (per-server override or global default)
+	DeferredExplicit  bool     // true = per-server override set, false = inherited from global
+	EnvKeys           []string // sorted env var names (values intentionally omitted)
+	EnvFile           string
+	Headers           []string // sorted header names
+}
+
+// MCPShowTool holds one tool's info for PrintMCPShow.
+type MCPShowTool struct {
+	Name        string
+	Description string
+	Parameters  []MCPShowParam
+}
+
+// MCPShowParam is one parameter entry.
+type MCPShowParam struct {
+	Name        string
+	Type        string
+	Description string
+	Required    bool
+}
+
+// PrintMCPShow renders the mcp show output (plain or fancy).
+// w is where the output is written; pass cmd.OutOrStdout() from cobra commands.
+func PrintMCPShow(w io.Writer, server MCPShowServer, tools []MCPShowTool, disabled bool) {
+	if !UseFancyLayout() {
+		printMCPShowPlain(w, server, tools, disabled)
+		return
+	}
+	printMCPShowFancy(w, server, tools, disabled)
+}
+
+// ── plain (narrow / non-TTY) ────────────────────────────────────────────────
+
+func printMCPShowPlain(w io.Writer, server MCPShowServer, tools []MCPShowTool, disabled bool) {
+	fmt.Fprintf(w, "Server: %s\n", server.Name)
+	fmt.Fprintf(w, "Type:   %s\n", server.Type)
+	fmt.Fprintf(w, "Target: %s\n", server.Target)
+	fmt.Fprintf(w, "Enabled: %s\n", boolWord(server.Enabled))
+	deferredLabel := boolWord(server.EffectiveDeferred)
+	if !server.DeferredExplicit {
+		deferredLabel += " (default)"
+	}
+	fmt.Fprintf(w, "Deferred: %s\n", deferredLabel)
+	if len(server.EnvKeys) > 0 {
+		fmt.Fprintf(w, "Env vars: %s\n", strings.Join(server.EnvKeys, ", "))
+	}
+	if server.EnvFile != "" {
+		fmt.Fprintf(w, "Env file: %s\n", server.EnvFile)
+	}
+	if len(server.Headers) > 0 {
+		fmt.Fprintf(w, "Headers: %s\n", strings.Join(server.Headers, ", "))
+	}
+	fmt.Fprintln(w)
+
+	if disabled {
+		fmt.Fprintln(w, "Server is disabled; skipping tool discovery.")
+		return
+	}
+	if len(tools) == 0 {
+		fmt.Fprintln(w, "No tools exposed by this server.")
+		return
+	}
+
+	fmt.Fprintf(w, "Tools (%d):\n", len(tools))
+	for _, tool := range tools {
+		fmt.Fprintf(w, "  %s\n", tool.Name)
+		if tool.Description != "" {
+			fmt.Fprintf(w, "    %s\n", truncateDescription(tool.Description, 120))
+		}
+		if len(tool.Parameters) == 0 {
+			fmt.Fprintln(w, "    Parameters: none")
+			continue
+		}
+		for _, p := range tool.Parameters {
+			line := fmt.Sprintf("    - %s", p.Name)
+			if p.Type != "" {
+				line += fmt.Sprintf(" (%s", p.Type)
+				if p.Required {
+					line += ", required"
+				}
+				line += ")"
+			} else if p.Required {
+				line += " (required)"
+			}
+			if p.Description != "" {
+				line += ": " + truncateDescription(p.Description, 80)
+			}
+			fmt.Fprintln(w, line)
+		}
+	}
+}
+
+// ── fancy (wide TTY) ────────────────────────────────────────────────────────
+
+var (
+	mcpToolNameStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(accentBlue).Bold(true)
+	}
+	mcpParamNameStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(accentRed).Bold(true)
+	}
+	mcpTagStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#888888"))
+	}
+	mcpRequiredStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#D54646")).Bold(true)
+	}
+	mcpOptionalStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#6B6B6B"))
+	}
+	mcpDescStyle = func() lipgloss.Style {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#CCCCCC"))
+	}
+)
+
+func printMCPShowFancy(w io.Writer, server MCPShowServer, tools []MCPShowTool, disabled bool) {
+	inner := InnerWidth()
+	box := borderStyle().Width(inner)
+
+	var b strings.Builder
+
+	// ── server header ──
+	b.WriteString(titleBarStyle().Render("⬡  " + server.Name))
+	b.WriteString("\n\n")
+
+	keyW := 10
+	writeKV := func(key, val string) {
+		k := kvKeyStyle().Width(keyW).Render(key)
+		b.WriteString(k + "  " + val + "\n")
+	}
+
+	writeKV("Type", server.Type)
+	writeKV("Target", server.Target)
+	writeKV("Enabled", coloredBool(server.Enabled))
+	deferredVal := coloredBool(server.EffectiveDeferred)
+	if !server.DeferredExplicit {
+		deferredVal += "  " + mcpTagStyle().Render("(default)")
+	}
+	writeKV("Deferred", deferredVal)
+	if len(server.EnvKeys) > 0 {
+		writeKV("Env vars", mutedStyle().Render(strings.Join(server.EnvKeys, ", ")))
+	}
+	if server.EnvFile != "" {
+		writeKV("Env file", mutedStyle().Render(server.EnvFile))
+	}
+	if len(server.Headers) > 0 {
+		writeKV("Headers", mutedStyle().Render(strings.Join(server.Headers, ", ")))
+	}
+
+	if disabled {
+		b.WriteString("\n")
+		b.WriteString(mutedStyle().Render("Server is disabled; skipping tool discovery."))
+		fmt.Fprintln(w, box.Render(b.String()))
+		return
+	}
+
+	if len(tools) == 0 {
+		b.WriteString("\n")
+		b.WriteString(mutedStyle().Render("No tools exposed by this server."))
+		fmt.Fprintln(w, box.Render(b.String()))
+		return
+	}
+
+	// ── tools section ──
+	b.WriteString("\n")
+	b.WriteString(kvKeyStyle().Render(fmt.Sprintf("Tools (%d)", len(tools))))
+	b.WriteString("\n")
+
+	contentW := inner - 4 // account for box padding
+	for i, tool := range tools {
+		if i > 0 {
+			b.WriteString(strings.Repeat("─", contentW) + "\n")
+		}
+		b.WriteString("\n")
+
+		// Tool name + index badge
+		badge := mcpTagStyle().Render(fmt.Sprintf("[%d/%d]", i+1, len(tools)))
+		b.WriteString("  " + mcpToolNameStyle().Render(tool.Name) + "  " + badge + "\n")
+
+		// Description (wrapped to content width)
+		if tool.Description != "" {
+			desc := truncateDescription(tool.Description, 160)
+			b.WriteString("  " + mcpDescStyle().Render(desc) + "\n")
+		}
+
+		// Parameters
+		if len(tool.Parameters) == 0 {
+			b.WriteString("  " + mcpTagStyle().Render("no parameters") + "\n")
+			continue
+		}
+
+		b.WriteString("\n")
+		for _, p := range tool.Parameters {
+			// name
+			pName := mcpParamNameStyle().Render(p.Name)
+
+			// type tag
+			typeTag := ""
+			if p.Type != "" {
+				typeTag = "  " + mcpTagStyle().Render("<"+p.Type+">")
+			}
+
+			// required / optional badge
+			var reqBadge string
+			if p.Required {
+				reqBadge = "  " + mcpRequiredStyle().Render("required")
+			} else {
+				reqBadge = "  " + mcpOptionalStyle().Render("optional")
+			}
+
+			b.WriteString("    " + pName + typeTag + reqBadge + "\n")
+
+			if p.Description != "" {
+				desc := truncateDescription(p.Description, 120)
+				b.WriteString("      " + mutedStyle().Render(desc) + "\n")
+			}
+		}
+	}
+
+	fmt.Fprintln(w, box.Render(b.String()))
+}
+
+// ── mcp list ────────────────────────────────────────────────────────────────
+
+// MCPListRow is one row in the mcp list output.
+type MCPListRow struct {
+	Name              string
+	Type              string
+	Target            string
+	Status            string // "enabled", "disabled", "ok (N tools)", "error"
+	EffectiveDeferred bool   // resolved value (per-server override or global default)
+	DeferredExplicit  bool   // true = per-server override set, false = inherited from global
+}
+
+// PrintMCPList renders the mcp list output (plain or fancy).
+func PrintMCPList(w io.Writer, rows []MCPListRow) {
+	if !UseFancyLayout() {
+		printMCPListPlain(w, rows)
+		return
+	}
+	printMCPListFancy(w, rows)
+}
+
+func printMCPListPlain(w io.Writer, rows []MCPListRow) {
+	headers := []string{"Name", "Type", "Command", "Status", "Deferred"}
+	tableRows := make([][]string, len(rows))
+	for i, r := range rows {
+		deferred := boolWord(r.EffectiveDeferred)
+		if !r.DeferredExplicit {
+			deferred += " (default)"
+		}
+		tableRows[i] = []string{r.Name, r.Type, r.Target, r.Status, deferred}
+	}
+	// reuse the ASCII table renderer already in helpers.go via the caller
+	// (list.go still uses renderTable for the plain path)
+	widths := make([]int, len(headers))
+	for i, h := range headers {
+		widths[i] = len(h)
+	}
+	for _, row := range tableRows {
+		for i, cell := range row {
+			if len(cell) > widths[i] {
+				widths[i] = len(cell)
+			}
+		}
+	}
+	border := func() {
+		fmt.Fprint(w, "+")
+		for _, width := range widths {
+			fmt.Fprint(w, strings.Repeat("-", width+2)+"+")
+		}
+		fmt.Fprintln(w)
+	}
+	writeRow := func(row []string) {
+		fmt.Fprint(w, "|")
+		for i, cell := range row {
+			fmt.Fprintf(w, " %s%s |", cell, strings.Repeat(" ", widths[i]-len(cell)))
+		}
+		fmt.Fprintln(w)
+	}
+	border()
+	writeRow(headers)
+	border()
+	for _, row := range tableRows {
+		writeRow(row)
+	}
+	border()
+}
+
+func printMCPListFancy(w io.Writer, rows []MCPListRow) {
+	inner := InnerWidth()
+	box := borderStyle().Width(inner)
+
+	var b strings.Builder
+
+	title := fmt.Sprintf("MCP Servers (%d)", len(rows))
+	b.WriteString(titleBarStyle().Render(title))
+	b.WriteString("\n")
+
+	contentW := inner - 4
+	for i, row := range rows {
+		if i > 0 {
+			b.WriteString(strings.Repeat("─", contentW) + "\n")
+		}
+		b.WriteString("\n")
+
+		statusBadge := mcpListStatusStyle(row.Status).Render(row.Status)
+		var deferredBadge string
+		if row.EffectiveDeferred {
+			if row.DeferredExplicit {
+				deferredBadge = "  " + mcpTagStyle().Render("deferred")
+			} else {
+				deferredBadge = "  " + mcpOptionalStyle().Render("deferred (default)")
+			}
+		}
+		b.WriteString("  " + mcpToolNameStyle().Render(row.Name) + "  " + statusBadge + deferredBadge + "\n")
+		b.WriteString("  " + mcpTagStyle().Render(row.Type+"  "+row.Target) + "\n")
+	}
+
+	fmt.Fprintln(w, box.Render(b.String()))
+}
+
+func mcpListStatusStyle(status string) lipgloss.Style {
+	switch {
+	case status == "enabled":
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#2E7D32")).Bold(true)
+	case status == "disabled":
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#6B6B6B"))
+	case strings.HasPrefix(status, "ok"):
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#2E7D32")).Bold(true)
+	case status == "error":
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#D54646")).Bold(true)
+	default:
+		return lipgloss.NewStyle()
+	}
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+func boolWord(v bool) string {
+	if v {
+		return "yes"
+	}
+	return "no"
+}
+
+func coloredBool(v bool) string {
+	if v {
+		return lipgloss.NewStyle().Foreground(lipgloss.Color("#2E7D32")).Bold(true).Render("yes")
+	}
+	return lipgloss.NewStyle().Foreground(lipgloss.Color("#D54646")).Render("no")
+}
+
+// truncateDescription strips newlines, collapses whitespace, and caps length.
+func truncateDescription(s string, maxLen int) string {
+	// collapse newlines and repeated spaces into a single space
+	s = strings.Join(strings.Fields(s), " ")
+	if len(s) <= maxLen {
+		return s
+	}
+	// cut at last space before maxLen
+	cut := s[:maxLen]
+	if idx := strings.LastIndex(cut, " "); idx > maxLen/2 {
+		cut = cut[:idx]
+	}
+	return cut + "…"
+}

cmd/picoclaw/internal/mcp/add.go

@@ -0,0 +1,249 @@
+package mcp
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type addOptions struct {
+	Env       []string
+	EnvFile   string
+	Headers   []string
+	Transport string
+	Force     bool
+	Deferred  *bool // nil = not set, true = deferred, false = not deferred
+}
+
+func newAddCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:                "add [flags] <name> <command-or-url> [args...]",
+		Short:              "Add or update an MCP server",
+		DisableFlagParsing: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts, name, target, targetArgs, showHelp, err := parseAddArgs(args)
+			if showHelp {
+				return cmd.Help()
+			}
+			if err != nil {
+				return err
+			}
+
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+			if cfg.Tools.MCP.Servers == nil {
+				cfg.Tools.MCP.Servers = make(map[string]config.MCPServerConfig)
+			}
+
+			if _, exists := cfg.Tools.MCP.Servers[name]; exists && !opts.Force {
+				var overwrite bool
+
+				overwrite, err = confirmOverwrite(cmd.InOrStdin(), cmd.OutOrStdout(), name)
+				if err != nil {
+					return fmt.Errorf("failed to confirm overwrite: %w", err)
+				}
+				if !overwrite {
+					return fmt.Errorf("aborted: MCP server %q already exists", name)
+				}
+			}
+
+			server, err := buildServerConfig(target, targetArgs, opts)
+			if err != nil {
+				return err
+			}
+
+			cfg.Tools.MCP.Enabled = true
+			cfg.Tools.MCP.Servers[name] = server
+
+			if err := saveValidatedConfig(cfg); err != nil {
+				return err
+			}
+
+			fmt.Fprintf(cmd.OutOrStdout(), "✓ MCP server %q saved.\n", name)
+			return nil
+		},
+	}
+
+	flags := cmd.Flags()
+	flags.StringArrayP("env", "e", nil, "Environment variable in KEY=value format (repeatable, saved to config)")
+	flags.String("env-file", "", "Path to an env file for stdio servers (recommended for secrets)")
+	flags.StringArrayP("header", "H", nil, "HTTP header in 'Name: Value' or 'Name=Value' format (repeatable)")
+	flags.StringP("transport", "t", "stdio", "Transport type: stdio, http, or sse")
+	flags.BoolP("force", "f", false, "Overwrite an existing server without prompting")
+	flags.Bool("deferred", false, "Mark server as deferred (tools hidden until explicitly activated)")
+	flags.Bool("no-deferred", false, "Mark server as non-deferred (tools always active)")
+
+	return cmd
+}
+
+func parseAddArgs(args []string) (addOptions, string, string, []string, bool, error) {
+	opts := addOptions{Transport: "stdio"}
+	var positional []string
+	serverArgs := make([]string, 0)
+	explicitCommand := make([]string, 0)
+
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+
+		switch {
+		case arg == "--help" || arg == "-h":
+			return addOptions{}, "", "", nil, true, nil
+		case arg == "--":
+			if i+1 < len(args) {
+				explicitCommand = append(explicitCommand, args[i+1:]...)
+			}
+			i = len(args)
+		case arg == "--force" || arg == "-f":
+			opts.Force = true
+		case arg == "--deferred":
+			t := true
+			opts.Deferred = &t
+		case arg == "--no-deferred":
+			f := false
+			opts.Deferred = &f
+		case arg == "--transport" || arg == "-t":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.Transport = args[i]
+		case strings.HasPrefix(arg, "--transport="):
+			opts.Transport = strings.TrimPrefix(arg, "--transport=")
+		case arg == "--env" || arg == "-e":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.Env = append(opts.Env, args[i])
+		case arg == "--env-file":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.EnvFile = args[i]
+		case strings.HasPrefix(arg, "--env="):
+			opts.Env = append(opts.Env, strings.TrimPrefix(arg, "--env="))
+		case strings.HasPrefix(arg, "--env-file="):
+			opts.EnvFile = strings.TrimPrefix(arg, "--env-file=")
+		case arg == "--header" || arg == "-H":
+			if i+1 >= len(args) {
+				return addOptions{}, "", "", nil, false, fmt.Errorf("missing value for %s", arg)
+			}
+			i++
+			opts.Headers = append(opts.Headers, args[i])
+		case strings.HasPrefix(arg, "--header="):
+			opts.Headers = append(opts.Headers, strings.TrimPrefix(arg, "--header="))
+		case strings.HasPrefix(arg, "-") && len(positional) >= 2:
+			serverArgs = append(serverArgs, args[i:]...)
+			i = len(args)
+		default:
+			positional = append(positional, arg)
+		}
+	}
+
+	if len(explicitCommand) > 0 {
+		if len(positional) != 1 {
+			return addOptions{}, "", "", nil, false, fmt.Errorf(
+				"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]",
+			)
+		}
+		if len(explicitCommand) == 0 {
+			return addOptions{}, "", "", nil, false, fmt.Errorf("missing stdio command after --")
+		}
+		return opts, positional[0], explicitCommand[0], explicitCommand[1:], false, nil
+	}
+
+	if len(positional) < 2 {
+		return addOptions{}, "", "", nil, false, fmt.Errorf(
+			"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]",
+		)
+	}
+
+	targetArgs := make([]string, 0, len(positional)-2+len(serverArgs))
+	targetArgs = append(targetArgs, positional[2:]...)
+	targetArgs = append(targetArgs, serverArgs...)
+
+	return opts, positional[0], positional[1], targetArgs, false, nil
+}
+
+func buildServerConfig(target string, args []string, opts addOptions) (config.MCPServerConfig, error) {
+	transport := strings.ToLower(strings.TrimSpace(opts.Transport))
+	if transport == "" {
+		transport = "stdio"
+	}
+	switch transport {
+	case "stdio", "http", "sse":
+	default:
+		return config.MCPServerConfig{}, fmt.Errorf("unsupported transport %q", opts.Transport)
+	}
+
+	env, err := parseEnvAssignments(opts.Env)
+	if err != nil {
+		return config.MCPServerConfig{}, err
+	}
+	headers, err := parseHeaderAssignments(opts.Headers)
+	if err != nil {
+		return config.MCPServerConfig{}, err
+	}
+
+	server := config.MCPServerConfig{
+		Enabled:  true,
+		Type:     transport,
+		Deferred: opts.Deferred,
+	}
+
+	switch transport {
+	case "http", "sse":
+		if len(env) > 0 {
+			return config.MCPServerConfig{}, fmt.Errorf("--env can only be used with stdio transport")
+		}
+		if strings.TrimSpace(opts.EnvFile) != "" {
+			return config.MCPServerConfig{}, fmt.Errorf("--env-file can only be used with stdio transport")
+		}
+		if len(args) > 0 {
+			return config.MCPServerConfig{}, fmt.Errorf("%s transport does not accept command arguments", transport)
+		}
+		parsedURL, err := url.ParseRequestURI(target)
+		if err != nil || parsedURL.Scheme == "" || parsedURL.Host == "" {
+			return config.MCPServerConfig{}, fmt.Errorf("invalid MCP URL %q", target)
+		}
+		server.URL = target
+		server.Headers = headers
+		return server, nil
+	}
+
+	if len(headers) > 0 {
+		return config.MCPServerConfig{}, fmt.Errorf("--header can only be used with http or sse transport")
+	}
+
+	if looksLikeRemoteURL(target) {
+		return config.MCPServerConfig{}, fmt.Errorf(
+			"target %q looks like a remote MCP URL, but transport is %q. Use --transport http or --transport sse",
+			target,
+			transport,
+		)
+	}
+
+	command := target
+	commandArgs := append([]string(nil), args...)
+
+	if err := validateLocalCommandPath(target); err != nil {
+		return config.MCPServerConfig{}, err
+	}
+	if isLocalCommandPath(command) {
+		command = expandHomePath(command)
+	}
+
+	server.Command = command
+	server.Args = commandArgs
+	server.Env = env
+	server.EnvFile = strings.TrimSpace(opts.EnvFile)
+
+	return server, nil
+}

cmd/picoclaw/internal/mcp/command.go

@@ -0,0 +1,25 @@
+package mcp
+
+import "github.com/spf13/cobra"
+
+func NewMCPCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "mcp",
+		Short: "Manage MCP server configuration",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	cmd.AddCommand(
+		newAddCommand(),
+		newRemoveCommand(),
+		newListCommand(),
+		newEditCommand(),
+		newTestCommand(),
+		newShowCommand(),
+	)
+
+	return cmd
+}

cmd/picoclaw/internal/mcp/command_test.go

@@ -0,0 +1,619 @@
+package mcp
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewMCPCommand(t *testing.T) {
+	cmd := NewMCPCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "mcp", cmd.Use)
+	assert.Equal(t, "Manage MCP server configuration", cmd.Short)
+	assert.True(t, cmd.HasSubCommands())
+
+	allowedCommands := []string{
+		"add",
+		"remove",
+		"list",
+		"edit",
+		"test",
+		"show",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+		assert.False(t, subcmd.Hidden)
+	}
+}
+
+func TestMCPAddAddsGenericStdioServer(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{
+		"add",
+		"sqlite",
+		"npx",
+		"-y",
+		"@modelcontextprotocol/server-sqlite",
+		"--db",
+		"./mydb.db",
+	}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, `MCP server "sqlite" saved`)
+
+	cfg := readMCPConfig(t, configPath)
+	require.True(t, cfg.Tools.MCP.Enabled)
+
+	server, ok := cfg.Tools.MCP.Servers["sqlite"]
+	require.True(t, ok)
+	assert.True(t, server.Enabled)
+	assert.Equal(t, "stdio", server.Type)
+	assert.Equal(t, "npx", server.Command)
+	assert.Equal(t, []string{"-y", "@modelcontextprotocol/server-sqlite", "--db", "./mydb.db"}, server.Args)
+}
+
+func TestMCPAddSupportsHeadersAfterURL(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"apify",
+		"https://mcp.apify.com/",
+		"-t",
+		"http",
+		"--header",
+		"Authorization: Bearer OMITTED",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["apify"]
+	assert.Equal(t, "http", server.Type)
+	assert.Equal(t, "https://mcp.apify.com/", server.URL)
+	assert.Equal(t, map[string]string{"Authorization": "Bearer OMITTED"}, server.Headers)
+}
+
+func TestMCPAddSupportsTransportBeforeName(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--transport",
+		"sse",
+		"fiscal-ai",
+		"https://api.fiscal.ai/mcp/sse",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["fiscal-ai"]
+	assert.Equal(t, "sse", server.Type)
+	assert.Equal(t, "https://api.fiscal.ai/mcp/sse", server.URL)
+}
+
+func TestMCPAddSupportsExplicitStdioCommandAfterSeparator(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--transport",
+		"stdio",
+		"--env",
+		"AIRTABLE_API_KEY=YOUR_KEY",
+		"airtable",
+		"--",
+		"npx",
+		"-y",
+		"airtable-mcp-server",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["airtable"]
+	assert.Equal(t, "stdio", server.Type)
+	assert.Equal(t, "npx", server.Command)
+	assert.Equal(t, []string{"-y", "airtable-mcp-server"}, server.Args)
+	assert.Equal(t, map[string]string{"AIRTABLE_API_KEY": "YOUR_KEY"}, server.Env)
+}
+
+func TestMCPAddSupportsEnvFileForStdio(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--env-file",
+		".env.mcp",
+		"filesystem",
+		"npx",
+		"-y",
+		"@modelcontextprotocol/server-filesystem",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["filesystem"]
+	assert.Equal(t, "stdio", server.Type)
+	assert.Equal(t, "npx", server.Command)
+	assert.Equal(t, []string{"-y", "@modelcontextprotocol/server-filesystem"}, server.Args)
+	assert.Equal(t, ".env.mcp", server.EnvFile)
+}
+
+func TestMCPAddRejectsEnvFileForHTTP(t *testing.T) {
+	setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"--transport",
+		"http",
+		"--env-file",
+		".env.mcp",
+		"context7",
+		"https://mcp.context7.com/mcp",
+	}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "--env-file can only be used with stdio transport")
+}
+
+func TestMCPAddRejectsNonExecutableLocalCommand(t *testing.T) {
+	setupMCPConfigEnv(t)
+
+	tmpDir := t.TempDir()
+	localCmd := filepath.Join(tmpDir, "server.sh")
+	require.NoError(t, os.WriteFile(localCmd, []byte("#!/bin/sh\nexit 0\n"), 0o644))
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "local", localCmd}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "not executable")
+}
+
+func TestMCPAddExpandsHomeInSavedLocalCommand(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	homeDir := t.TempDir()
+	t.Setenv("HOME", homeDir)
+	t.Setenv("USERPROFILE", homeDir)
+
+	localCmd := filepath.Join(homeDir, "bin", "my-mcp")
+	require.NoError(t, os.MkdirAll(filepath.Dir(localCmd), 0o755))
+	require.NoError(t, os.WriteFile(localCmd, []byte("#!/bin/sh\nexit 0\n"), 0o755))
+
+	tildeCmd := "~" + string(os.PathSeparator) + filepath.Join("bin", "my-mcp")
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "local-home", tildeCmd}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["local-home"]
+	assert.Equal(t, localCmd, server.Command)
+}
+
+func TestMCPAddShowsClearErrorForRemoteURLWithoutTransport(t *testing.T) {
+	setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "apify", "https://mcp.apify.com/"}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `looks like a remote MCP URL`)
+	assert.Contains(t, err.Error(), `Use --transport http or --transport sse`)
+}
+
+func TestMCPAddOverwritePromptDecline(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "old",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"add", "filesystem", "new-command"}, "n\n")
+	require.Error(t, err)
+	assert.Contains(t, output, `Overwrite? [y/N]:`)
+	assert.Contains(t, err.Error(), "aborted")
+
+	cfg := readMCPConfig(t, configPath)
+	assert.Equal(t, "old", cfg.Tools.MCP.Servers["filesystem"].Command)
+}
+
+func TestMCPAddOverwriteWithConfirmation(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "old",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "filesystem", "new-command"}, "y\n")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	assert.Equal(t, "new-command", cfg.Tools.MCP.Servers["filesystem"].Command)
+}
+
+func TestMCPAddHTTPServer(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{
+		"add",
+		"context7",
+		"--transport",
+		"http",
+		"https://mcp.context7.com/mcp",
+	}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["context7"]
+	assert.Equal(t, "http", server.Type)
+	assert.Equal(t, "https://mcp.context7.com/mcp", server.URL)
+	assert.Empty(t, server.Command)
+}
+
+func TestMCPRemoveRemovesLastServerAndDisablesMCP(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"remove", "filesystem"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, `MCP server "filesystem" removed`)
+
+	cfg := readMCPConfig(t, configPath)
+	assert.False(t, cfg.Tools.MCP.Enabled)
+	assert.Empty(t, cfg.Tools.MCP.Servers)
+}
+
+func TestMCPListPrintsTable(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"context7": {
+						Enabled: true,
+						Type:    "http",
+						URL:     "https://mcp.context7.com/mcp",
+					},
+					"filesystem": {
+						Enabled: false,
+						Type:    "stdio",
+						Command: "npx",
+						Args:    []string{"-y", "@modelcontextprotocol/server-filesystem", "/tmp"},
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"list"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "| Name")
+	assert.Contains(t, output, "context7")
+	assert.Contains(t, output, "filesystem")
+	assert.Contains(t, output, "https://mcp.context7.com/mcp")
+	assert.Contains(t, output, "disabled")
+}
+
+func TestMCPListWithStatusUsesProbe(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	originalProbe := serverProbe
+	defer func() { serverProbe = originalProbe }()
+	serverProbe = func(_ context.Context, name string, server config.MCPServerConfig, workspacePath string) (probeResult, error) {
+		assert.Equal(t, "filesystem", name)
+		assert.Equal(t, readMCPConfig(t, configPath).WorkspacePath(), workspacePath)
+		assert.Equal(t, "npx", server.Command)
+		return probeResult{ToolCount: 3}, nil
+	}
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"list", "--status"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "ok (3 tools)")
+}
+
+func TestMCPEditUsesEditor(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	originalEditor := editorCommand
+	defer func() { editorCommand = originalEditor }()
+
+	var gotName string
+	var gotArgs []string
+	editorCommand = func(name string, args ...string) *exec.Cmd {
+		gotName = name
+		gotArgs = append([]string(nil), args...)
+		return exec.Command("sh", "-c", "exit 0")
+	}
+
+	t.Setenv("EDITOR", `dummy-editor --wait`)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"edit"}, "")
+	require.NoError(t, err)
+
+	assert.Equal(t, "dummy-editor", gotName)
+	assert.Equal(t, []string{"--wait", configPath}, gotArgs)
+	_, statErr := os.Stat(configPath)
+	assert.NoError(t, statErr)
+}
+
+func TestMCPEditRequiresEditor(t *testing.T) {
+	setupMCPConfigEnv(t)
+	t.Setenv("EDITOR", "")
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"edit"}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "$EDITOR is not set")
+}
+
+func TestMCPTestUsesProbe(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"filesystem": {
+						Enabled: false,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	originalProbe := serverProbe
+	defer func() { serverProbe = originalProbe }()
+	serverProbe = func(_ context.Context, name string, _ config.MCPServerConfig, workspacePath string) (probeResult, error) {
+		assert.Equal(t, "filesystem", name)
+		assert.Equal(t, readMCPConfig(t, configPath).WorkspacePath(), workspacePath)
+		return probeResult{ToolCount: 2}, nil
+	}
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"test", "filesystem"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, `MCP server "filesystem" reachable (2 tools)`)
+}
+
+func TestMCPAddDeferredFlag(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "--deferred", "myserver", "npx", "my-mcp"}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["myserver"]
+	require.NotNil(t, server.Deferred)
+	assert.True(t, *server.Deferred)
+}
+
+func TestMCPAddNoDeferredFlag(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "--no-deferred", "myserver", "npx", "my-mcp"}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["myserver"]
+	require.NotNil(t, server.Deferred)
+	assert.False(t, *server.Deferred)
+}
+
+func TestMCPAddNoDeferredByDefault(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"add", "myserver", "npx", "my-mcp"}, "")
+	require.NoError(t, err)
+
+	cfg := readMCPConfig(t, configPath)
+	server := cfg.Tools.MCP.Servers["myserver"]
+	assert.Nil(t, server.Deferred)
+}
+
+func TestMCPShowNotFound(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, nil)
+
+	cmd := NewMCPCommand()
+	_, err := executeCommand(cmd, []string{"show", "missing"}, "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), `"missing" not found`)
+}
+
+func TestMCPShowDisabledServer(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"myserver": {
+						Enabled: false,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"show", "myserver"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "myserver")
+	assert.Contains(t, output, "disabled")
+}
+
+func TestMCPShowUsesProbe(t *testing.T) {
+	configPath := setupMCPConfigEnv(t)
+	writeMCPConfig(t, configPath, &config.Config{
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{Enabled: true},
+				Servers: map[string]config.MCPServerConfig{
+					"myserver": {
+						Enabled: true,
+						Type:    "stdio",
+						Command: "npx",
+					},
+				},
+			},
+		},
+	})
+
+	original := serverShowProbe
+	defer func() { serverShowProbe = original }()
+	serverShowProbe = func(_ context.Context, name string, _ config.MCPServerConfig, _ string) ([]toolDetail, error) {
+		assert.Equal(t, "myserver", name)
+		return []toolDetail{
+			{
+				Name:        "read_file",
+				Description: "Read a file from the filesystem",
+				Parameters: []paramDetail{
+					{Name: "path", Type: "string", Description: "File path", Required: true},
+					{Name: "encoding", Type: "string", Description: "Character encoding", Required: false},
+				},
+			},
+			{
+				Name:        "list_dir",
+				Description: "List directory contents",
+				Parameters:  nil,
+			},
+		}, nil
+	}
+
+	cmd := NewMCPCommand()
+	output, err := executeCommand(cmd, []string{"show", "myserver"}, "")
+	require.NoError(t, err)
+	assert.Contains(t, output, "myserver")
+	assert.Contains(t, output, "read_file")
+	assert.Contains(t, output, "Read a file from the filesystem")
+	assert.Contains(t, output, "path")
+	assert.Contains(t, output, "string")
+	assert.Contains(t, output, "required")
+	assert.Contains(t, output, "list_dir")
+	assert.Contains(t, output, "none")
+}
+
+func setupMCPConfigEnv(t *testing.T) string {
+	t.Helper()
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	t.Setenv(config.EnvConfig, configPath)
+	t.Setenv(config.EnvHome, filepath.Dir(configPath))
+	return configPath
+}
+
+func writeMCPConfig(t *testing.T, path string, cfg *config.Config) {
+	t.Helper()
+
+	if cfg == nil {
+		cfg = config.DefaultConfig()
+	}
+
+	require.NoError(t, config.SaveConfig(path, cfg))
+}
+
+func readMCPConfig(t *testing.T, path string) *config.Config {
+	t.Helper()
+
+	cfg, err := config.LoadConfig(path)
+	require.NoError(t, err)
+	return cfg
+}
+
+func executeCommand(cmd *cobra.Command, args []string, stdin string) (string, error) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	cmd.SetArgs(args)
+	cmd.SetOut(&stdout)
+	cmd.SetErr(&stderr)
+	cmd.SetIn(strings.NewReader(stdin))
+
+	err := cmd.Execute()
+	return stdout.String() + stderr.String(), err
+}

cmd/picoclaw/internal/mcp/edit.go

@@ -0,0 +1,54 @@
+package mcp
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"go.mau.fi/util/shlex"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func newEditCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "edit",
+		Short: "Open the PicoClaw config in $EDITOR",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			editor := strings.TrimSpace(os.Getenv("EDITOR"))
+			if editor == "" {
+				return fmt.Errorf("$EDITOR is not set")
+			}
+
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+			if err = saveValidatedConfig(cfg); err != nil {
+				return err
+			}
+
+			editorArgs, err := shlex.Split(editor)
+			if err != nil {
+				return fmt.Errorf("failed to parse $EDITOR: %w", err)
+			}
+			if len(editorArgs) == 0 {
+				return fmt.Errorf("$EDITOR is empty")
+			}
+
+			editorArgs = append(editorArgs, internal.GetConfigPath())
+			process := editorCommand(editorArgs[0], editorArgs[1:]...)
+			process.Stdin = cmd.InOrStdin()
+			process.Stdout = cmd.OutOrStdout()
+			process.Stderr = cmd.ErrOrStderr()
+
+			if err := process.Run(); err != nil {
+				return fmt.Errorf("failed to start editor: %w", err)
+			}
+
+			return nil
+		},
+	}
+}

cmd/picoclaw/internal/mcp/helpers.go

@@ -0,0 +1,359 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strings"
+	"sync"
+
+	"github.com/google/jsonschema-go/jsonschema"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+	picomcp "github.com/sipeed/picoclaw/pkg/mcp"
+)
+
+type probeResult struct {
+	ToolCount int
+}
+
+var (
+	editorCommand = exec.Command
+	serverProbe   = defaultServerProbe
+
+	mcpConfigSchemaOnce sync.Once
+	mcpConfigSchema     *jsonschema.Resolved
+	errMcpConfigSchema  error
+)
+
+const mcpConfigSchemaJSON = `{
+  "type": "object",
+  "properties": {
+    "tools": {
+      "type": "object",
+      "properties": {
+        "mcp": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "discovery": { "type": "object", "additionalProperties": true },
+            "max_inline_text_chars": { "type": "integer" },
+            "servers": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "enabled": { "type": "boolean" },
+                  "deferred": { "type": "boolean" },
+                  "command": { "type": "string" },
+                  "args": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  },
+                  "env": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  },
+                  "env_file": { "type": "string" },
+                  "type": {
+                    "type": "string",
+                    "enum": ["stdio", "http", "sse"]
+                  },
+                  "url": { "type": "string" },
+                  "headers": {
+                    "type": "object",
+                    "additionalProperties": { "type": "string" }
+                  }
+                },
+                "required": ["enabled"],
+                "anyOf": [
+                  { "required": ["command"] },
+                  { "required": ["url"] }
+                ],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": ["enabled"],
+          "additionalProperties": true
+        }
+      },
+      "required": ["mcp"],
+      "additionalProperties": true
+    }
+  },
+  "required": ["tools"],
+  "additionalProperties": true
+}`
+
+func loadConfig() (*config.Config, error) {
+	cfg, err := config.LoadConfig(internal.GetConfigPath())
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+	return cfg, nil
+}
+
+func saveValidatedConfig(cfg *config.Config) error {
+	if cfg == nil {
+		return fmt.Errorf("config is nil")
+	}
+
+	data, err := json.Marshal(cfg)
+	if err != nil {
+		return fmt.Errorf("failed to serialize config: %w", err)
+	}
+
+	if err := validateConfigDocument(data); err != nil {
+		return err
+	}
+
+	if err := config.SaveConfig(internal.GetConfigPath(), cfg); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	return nil
+}
+
+func validateConfigDocument(data []byte) error {
+	var instance map[string]any
+	if err := json.Unmarshal(data, &instance); err != nil {
+		return fmt.Errorf("failed to decode serialized config: %w", err)
+	}
+
+	schema, err := loadMCPConfigSchema()
+	if err != nil {
+		return fmt.Errorf("failed to load MCP config schema: %w", err)
+	}
+
+	if err := schema.Validate(instance); err != nil {
+		return fmt.Errorf("config validation failed: %w", err)
+	}
+
+	return nil
+}
+
+func loadMCPConfigSchema() (*jsonschema.Resolved, error) {
+	mcpConfigSchemaOnce.Do(func() {
+		var schema jsonschema.Schema
+		if err := json.Unmarshal([]byte(mcpConfigSchemaJSON), &schema); err != nil {
+			errMcpConfigSchema = err
+			return
+		}
+		mcpConfigSchema, errMcpConfigSchema = schema.Resolve(nil)
+	})
+
+	return mcpConfigSchema, errMcpConfigSchema
+}
+
+func inferTransportType(server config.MCPServerConfig) string {
+	switch server.Type {
+	case "stdio", "http", "sse":
+		return server.Type
+	}
+	if server.URL != "" {
+		return "sse"
+	}
+	if server.Command != "" {
+		return "stdio"
+	}
+	return "unknown"
+}
+
+func renderServerTarget(server config.MCPServerConfig) string {
+	transport := inferTransportType(server)
+	if transport == "http" || transport == "sse" {
+		if server.URL == "" {
+			return "<missing url>"
+		}
+		return server.URL
+	}
+
+	parts := append([]string{server.Command}, server.Args...)
+	rendered := strings.TrimSpace(strings.Join(parts, " "))
+	if rendered == "" {
+		return "<missing command>"
+	}
+	return rendered
+}
+
+func sortedServerNames(servers map[string]config.MCPServerConfig) []string {
+	names := make([]string, 0, len(servers))
+	for name := range servers {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+func parseEnvAssignments(values []string) (map[string]string, error) {
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	env := make(map[string]string, len(values))
+	for _, entry := range values {
+		key, value, found := strings.Cut(entry, "=")
+		if !found {
+			return nil, fmt.Errorf("invalid env assignment %q: expected KEY=value", entry)
+		}
+		key = strings.TrimSpace(key)
+		if key == "" {
+			return nil, fmt.Errorf("invalid env assignment %q: key cannot be empty", entry)
+		}
+		env[key] = value
+	}
+
+	return env, nil
+}
+
+func parseHeaderAssignments(values []string) (map[string]string, error) {
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	headers := make(map[string]string, len(values))
+	for _, entry := range values {
+		key, value, found := strings.Cut(entry, ":")
+		if !found {
+			key, value, found = strings.Cut(entry, "=")
+		}
+		if !found {
+			return nil, fmt.Errorf("invalid header %q: expected 'Name: Value' or 'Name=Value'", entry)
+		}
+		key = strings.TrimSpace(key)
+		value = strings.TrimSpace(value)
+		if key == "" {
+			return nil, fmt.Errorf("invalid header %q: name cannot be empty", entry)
+		}
+		headers[key] = value
+	}
+
+	return headers, nil
+}
+
+func looksLikeRemoteURL(target string) bool {
+	parsedURL, err := url.ParseRequestURI(target)
+	if err != nil {
+		return false
+	}
+	if parsedURL.Host == "" {
+		return false
+	}
+	switch strings.ToLower(parsedURL.Scheme) {
+	case "http", "https":
+		return true
+	default:
+		return false
+	}
+}
+
+func isLocalCommandPath(command string) bool {
+	if command == "" {
+		return false
+	}
+	if looksLikeRemoteURL(command) {
+		return false
+	}
+	return filepath.IsAbs(command) ||
+		filepath.VolumeName(command) != "" ||
+		strings.HasPrefix(command, "."+string(os.PathSeparator)) ||
+		strings.HasPrefix(command, ".."+string(os.PathSeparator)) ||
+		command == "." ||
+		command == ".." ||
+		strings.ContainsRune(command, os.PathSeparator)
+}
+
+func expandHomePath(path string) string {
+	if path == "" || path[0] != '~' {
+		return path
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return path
+	}
+	if path == "~" {
+		return home
+	}
+	if strings.HasPrefix(path, "~/") || strings.HasPrefix(path, "~\\") {
+		return filepath.Join(home, path[2:])
+	}
+	return path
+}
+
+func validateLocalCommandPath(command string) error {
+	if !isLocalCommandPath(command) {
+		return nil
+	}
+
+	path := expandHomePath(command)
+	info, err := os.Stat(path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return fmt.Errorf("local command %q does not exist", command)
+		}
+		return fmt.Errorf("failed to stat local command %q: %w", command, err)
+	}
+	if info.IsDir() {
+		return fmt.Errorf("local command %q is a directory", command)
+	}
+	if runtime.GOOS != "windows" && info.Mode()&0o111 == 0 {
+		return fmt.Errorf("local command %q is not executable", command)
+	}
+	return nil
+}
+
+func defaultServerProbe(
+	ctx context.Context,
+	name string,
+	server config.MCPServerConfig,
+	workspacePath string,
+) (probeResult, error) {
+	mgr := picomcp.NewManager()
+	defer func() { _ = mgr.Close() }()
+
+	server.Enabled = true
+	mcpCfg := config.MCPConfig{
+		ToolConfig: config.ToolConfig{Enabled: true},
+		Servers: map[string]config.MCPServerConfig{
+			name: server,
+		},
+	}
+
+	if err := mgr.LoadFromMCPConfig(ctx, mcpCfg, workspacePath); err != nil {
+		return probeResult{}, err
+	}
+
+	conn, ok := mgr.GetServer(name)
+	if !ok {
+		return probeResult{}, fmt.Errorf("server %q did not register a connection", name)
+	}
+
+	return probeResult{ToolCount: len(conn.Tools)}, nil
+}
+
+func confirmOverwrite(r io.Reader, w io.Writer, name string) (bool, error) {
+	if _, err := fmt.Fprintf(w, "MCP server %q already exists. Overwrite? [y/N]: ", name); err != nil {
+		return false, err
+	}
+
+	var answer string
+	if _, err := fmt.Fscanln(r, &answer); err != nil {
+		if errors.Is(err, io.EOF) {
+			return false, nil
+		}
+		return false, err
+	}
+
+	answer = strings.TrimSpace(strings.ToLower(answer))
+	return answer == "y" || answer == "yes", nil
+}

cmd/picoclaw/internal/mcp/list.go

@@ -0,0 +1,78 @@
+package mcp
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cliui"
+)
+
+func newListCommand() *cobra.Command {
+	var (
+		includeStatus bool
+		timeout       time.Duration
+	)
+
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List configured MCP servers",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			if len(cfg.Tools.MCP.Servers) == 0 {
+				fmt.Fprintln(cmd.OutOrStdout(), "No MCP servers configured.")
+				return nil
+			}
+
+			rows := make([]cliui.MCPListRow, 0, len(cfg.Tools.MCP.Servers))
+			for _, name := range sortedServerNames(cfg.Tools.MCP.Servers) {
+				server := cfg.Tools.MCP.Servers[name]
+				status := "disabled"
+				if server.Enabled {
+					status = "enabled"
+				}
+
+				if includeStatus && server.Enabled {
+					ctx, cancel := context.WithTimeout(context.Background(), timeout)
+					result, probeErr := serverProbe(ctx, name, server, cfg.WorkspacePath())
+					cancel()
+					if probeErr != nil {
+						status = "error"
+					} else {
+						status = fmt.Sprintf("ok (%d tools)", result.ToolCount)
+					}
+				}
+
+				effectiveDeferred := cfg.Tools.MCP.Discovery.Enabled
+				deferredExplicit := server.Deferred != nil
+				if deferredExplicit {
+					effectiveDeferred = *server.Deferred
+				}
+
+				rows = append(rows, cliui.MCPListRow{
+					Name:              name,
+					Type:              inferTransportType(server),
+					Target:            renderServerTarget(server),
+					Status:            status,
+					EffectiveDeferred: effectiveDeferred,
+					DeferredExplicit:  deferredExplicit,
+				})
+			}
+
+			cliui.PrintMCPList(cmd.OutOrStdout(), rows)
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&includeStatus, "status", false, "Ping enabled servers and show live status")
+	cmd.Flags().DurationVar(&timeout, "timeout", 5*time.Second, "Timeout for each live status check")
+
+	return cmd
+}

cmd/picoclaw/internal/mcp/remove.go

@@ -0,0 +1,39 @@
+package mcp
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+func newRemoveCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "remove <name>",
+		Short: "Remove an MCP server from config",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			name := args[0]
+			if _, exists := cfg.Tools.MCP.Servers[name]; !exists {
+				return fmt.Errorf("MCP server %q not found", name)
+			}
+
+			delete(cfg.Tools.MCP.Servers, name)
+			if len(cfg.Tools.MCP.Servers) == 0 {
+				cfg.Tools.MCP.Servers = nil
+				cfg.Tools.MCP.Enabled = false
+			}
+
+			if err := saveValidatedConfig(cfg); err != nil {
+				return err
+			}
+
+			fmt.Fprintf(cmd.OutOrStdout(), "✓ MCP server %q removed.\n", name)
+			return nil
+		},
+	}
+}

cmd/picoclaw/internal/mcp/show.go

@@ -0,0 +1,237 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cliui"
+	"github.com/sipeed/picoclaw/pkg/config"
+	picomcp "github.com/sipeed/picoclaw/pkg/mcp"
+)
+
+type toolDetail struct {
+	Name        string
+	Description string
+	Parameters  []paramDetail
+}
+
+type paramDetail struct {
+	Name        string
+	Type        string
+	Description string
+	Required    bool
+}
+
+var serverShowProbe = defaultServerShowProbe
+
+func defaultServerShowProbe(
+	ctx context.Context,
+	name string,
+	server config.MCPServerConfig,
+	workspacePath string,
+) ([]toolDetail, error) {
+	mgr := picomcp.NewManager()
+	defer func() { _ = mgr.Close() }()
+
+	server.Enabled = true
+	mcpCfg := config.MCPConfig{
+		ToolConfig: config.ToolConfig{Enabled: true},
+		Servers: map[string]config.MCPServerConfig{
+			name: server,
+		},
+	}
+
+	if err := mgr.LoadFromMCPConfig(ctx, mcpCfg, workspacePath); err != nil {
+		return nil, err
+	}
+
+	conn, ok := mgr.GetServer(name)
+	if !ok {
+		return nil, fmt.Errorf("server %q did not register a connection", name)
+	}
+
+	details := make([]toolDetail, 0, len(conn.Tools))
+	for _, tool := range conn.Tools {
+		details = append(details, toolDetail{
+			Name:        tool.Name,
+			Description: tool.Description,
+			Parameters:  extractParameters(tool.InputSchema),
+		})
+	}
+	return details, nil
+}
+
+func extractParameters(schema any) []paramDetail {
+	schemaMap := normalizeSchema(schema)
+	properties, ok := schemaMap["properties"].(map[string]any)
+	if !ok || len(properties) == 0 {
+		return nil
+	}
+
+	required := make(map[string]struct{})
+	switch raw := schemaMap["required"].(type) {
+	case []string:
+		for _, name := range raw {
+			required[name] = struct{}{}
+		}
+	case []any:
+		for _, value := range raw {
+			if name, ok := value.(string); ok {
+				required[name] = struct{}{}
+			}
+		}
+	}
+
+	names := make([]string, 0, len(properties))
+	for name := range properties {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	params := make([]paramDetail, 0, len(names))
+	for _, name := range names {
+		param := paramDetail{Name: name}
+		if propMap, ok := properties[name].(map[string]any); ok {
+			if typeName, ok := propMap["type"].(string); ok {
+				param.Type = strings.TrimSpace(typeName)
+			}
+			if desc, ok := propMap["description"].(string); ok {
+				param.Description = strings.TrimSpace(desc)
+			}
+		}
+		_, param.Required = required[name]
+		params = append(params, param)
+	}
+	return params
+}
+
+func normalizeSchema(schema any) map[string]any {
+	if schema == nil {
+		return map[string]any{}
+	}
+	if schemaMap, ok := schema.(map[string]any); ok {
+		return schemaMap
+	}
+
+	var jsonData []byte
+	switch raw := schema.(type) {
+	case json.RawMessage:
+		jsonData = raw
+	case []byte:
+		jsonData = raw
+	default:
+		var err error
+		jsonData, err = json.Marshal(schema)
+		if err != nil {
+			return map[string]any{}
+		}
+	}
+
+	var result map[string]any
+	if err := json.Unmarshal(jsonData, &result); err != nil {
+		return map[string]any{}
+	}
+	return result
+}
+
+func newShowCommand() *cobra.Command {
+	var timeout time.Duration
+
+	cmd := &cobra.Command{
+		Use:   "show <name>",
+		Short: "Show details and tools for a configured MCP server",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			name := args[0]
+			server, exists := cfg.Tools.MCP.Servers[name]
+			if !exists {
+				return fmt.Errorf("MCP server %q not found", name)
+			}
+
+			serverInfo := buildServerInfo(name, server, cfg.Tools.MCP.Discovery.Enabled)
+
+			if !server.Enabled {
+				cliui.PrintMCPShow(cmd.OutOrStdout(), serverInfo, nil, true)
+				return nil
+			}
+
+			ctx, cancel := context.WithTimeout(context.Background(), timeout)
+			defer cancel()
+
+			details, err := serverShowProbe(ctx, name, server, cfg.WorkspacePath())
+			if err != nil {
+				return fmt.Errorf("failed to connect to MCP server %q: %w", name, err)
+			}
+
+			tools := make([]cliui.MCPShowTool, 0, len(details))
+			for _, d := range details {
+				params := make([]cliui.MCPShowParam, 0, len(d.Parameters))
+				for _, p := range d.Parameters {
+					params = append(params, cliui.MCPShowParam{
+						Name:        p.Name,
+						Type:        p.Type,
+						Description: p.Description,
+						Required:    p.Required,
+					})
+				}
+				tools = append(tools, cliui.MCPShowTool{
+					Name:        d.Name,
+					Description: d.Description,
+					Parameters:  params,
+				})
+			}
+
+			cliui.PrintMCPShow(cmd.OutOrStdout(), serverInfo, tools, false)
+			return nil
+		},
+	}
+
+	cmd.Flags().DurationVar(&timeout, "timeout", 10*time.Second, "Connection timeout")
+
+	return cmd
+}
+
+func buildServerInfo(name string, server config.MCPServerConfig, discoveryEnabled bool) cliui.MCPShowServer {
+	effectiveDeferred := discoveryEnabled
+	deferredExplicit := server.Deferred != nil
+	if deferredExplicit {
+		effectiveDeferred = *server.Deferred
+	}
+	info := cliui.MCPShowServer{
+		Name:              name,
+		Type:              inferTransportType(server),
+		Target:            renderServerTarget(server),
+		Enabled:           server.Enabled,
+		EffectiveDeferred: effectiveDeferred,
+		DeferredExplicit:  deferredExplicit,
+		EnvFile:           server.EnvFile,
+	}
+	if len(server.Env) > 0 {
+		keys := make([]string, 0, len(server.Env))
+		for k := range server.Env {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		info.EnvKeys = keys
+	}
+	if len(server.Headers) > 0 {
+		keys := make([]string, 0, len(server.Headers))
+		for k := range server.Headers {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		info.Headers = keys
+	}
+	return info
+}

cmd/picoclaw/internal/mcp/test.go

@@ -0,0 +1,46 @@
+package mcp
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+func newTestCommand() *cobra.Command {
+	var timeout time.Duration
+
+	cmd := &cobra.Command{
+		Use:   "test <name>",
+		Short: "Test connectivity for a configured MCP server",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := loadConfig()
+			if err != nil {
+				return err
+			}
+
+			name := args[0]
+			server, exists := cfg.Tools.MCP.Servers[name]
+			if !exists {
+				return fmt.Errorf("MCP server %q not found", name)
+			}
+
+			ctx, cancel := context.WithTimeout(context.Background(), timeout)
+			defer cancel()
+
+			result, err := serverProbe(ctx, name, server, cfg.WorkspacePath())
+			if err != nil {
+				return fmt.Errorf("failed to reach MCP server %q: %w", name, err)
+			}
+
+			fmt.Fprintf(cmd.OutOrStdout(), "✓ MCP server %q reachable (%d tools).\n", name, result.ToolCount)
+			return nil
+		},
+	}
+
+	cmd.Flags().DurationVar(&timeout, "timeout", 5*time.Second, "Connection timeout")
+
+	return cmd
+}

cmd/picoclaw/internal/model/add.go

@@ -0,0 +1,200 @@
+package model
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const defaultAliasName = "custom-prefer"
+
+func newAddCommand() *cobra.Command {
+	var (
+		apiBase   string
+		apiKey    string
+		modelID   string
+		alias     string
+		modelType string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "add",
+		Short: "Add a model from an OpenAI-compatible endpoint",
+		Long: `Add a model entry by querying an OpenAI-compatible endpoint exposing
+GET <api-base>/models, then setting it as the default model.
+
+If --model is omitted, the available models are listed and you can pick one
+interactively. If --model is provided, the entry is written without contacting
+the server.
+
+Sample interactive session (key shown masked):
+
+    $ picoclaw model add \
+        -b https://ark.cn-beijing.volces.com/api/v3 \
+        -k 7dff****-****-****-****-********e829
+
+    115 model(s) available:
+        1) doubao-lite-128k-240428    (doubao-lite-128k)
+        2) doubao-pro-128k-240515     (doubao-pro-128k)
+        ...
+       48) deepseek-r1-250120          (deepseek-r1)
+       78) kimi-k2-250711              (kimi-k2)
+        ...
+      115) doubao-seed3d-2-0-260328    (doubao-seed3d-2-0)
+    Pick a model (number or id): 48
+    ✓ Saved model 'custom-prefer' (deepseek-r1-250120) and set as default.`,
+		Example: `  picoclaw model add --api-base https://api.openai.com/v1 --api-key sk-...
+  picoclaw model add -b http://localhost:8000/v1 -k dummy -m my-model -n local`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runAdd(addOptions{
+				apiBase:   strings.TrimSpace(apiBase),
+				apiKey:    strings.TrimSpace(apiKey),
+				modelID:   strings.TrimSpace(modelID),
+				alias:     strings.TrimSpace(alias),
+				modelType: strings.TrimSpace(modelType),
+				stdin:     cmd.InOrStdin(),
+				stdout:    cmd.OutOrStdout(),
+			})
+		},
+	}
+
+	cmd.Flags().StringVarP(&apiBase, "api-base", "b", "",
+		"API base URL (required), e.g. https://api.openai.com/v1")
+	cmd.Flags().StringVarP(&apiKey, "api-key", "k", "", "API key (required)")
+	cmd.Flags().StringVarP(&modelID, "model", "m", "",
+		"Model id; when set, skips the interactive picker and the network call")
+	cmd.Flags().StringVarP(&alias, "name", "n", defaultAliasName,
+		"Local alias written to model_list and used as the default model name")
+	cmd.Flags().StringVar(&modelType, "type", "openai-compatible",
+		"Endpoint type (only 'openai-compatible' is supported today)")
+	_ = cmd.MarkFlagRequired("api-base")
+	_ = cmd.MarkFlagRequired("api-key")
+
+	return cmd
+}
+
+type addOptions struct {
+	apiBase   string
+	apiKey    string
+	modelID   string
+	alias     string
+	modelType string
+	stdin     io.Reader
+	stdout    io.Writer
+}
+
+func runAdd(opt addOptions) error {
+	if opt.modelType != "" && opt.modelType != "openai-compatible" {
+		return fmt.Errorf("unsupported --type %q (only 'openai-compatible' is supported)", opt.modelType)
+	}
+	if opt.alias == "" {
+		opt.alias = defaultAliasName
+	}
+
+	selected := opt.modelID
+	if selected == "" {
+		entries, err := fetchOpenAIModels(opt.apiBase, opt.apiKey)
+		if err != nil {
+			return fmt.Errorf("fetch models: %w", err)
+		}
+		if len(entries) == 0 {
+			return fmt.Errorf("no models returned by %s", opt.apiBase)
+		}
+		selected, err = pickModel(opt.stdin, opt.stdout, entries)
+		if err != nil {
+			return err
+		}
+	}
+
+	return upsertModelDefault(opt.apiBase, opt.apiKey, opt.alias, selected, opt.stdout)
+}
+
+func pickModel(stdin io.Reader, stdout io.Writer, entries []modelEntry) (string, error) {
+	fmt.Fprintf(stdout, "\n%d model(s) available:\n", len(entries))
+	for i, m := range entries {
+		line := m.ID
+		if m.Name != "" && m.Name != m.ID {
+			line = fmt.Sprintf("%s (%s)", m.ID, m.Name)
+		}
+		fmt.Fprintf(stdout, "  %3d) %s\n", i+1, line)
+	}
+
+	scanner := bufio.NewScanner(stdin)
+	for {
+		fmt.Fprint(stdout, "Pick a model (number or id): ")
+		if !scanner.Scan() {
+			if err := scanner.Err(); err != nil {
+				return "", fmt.Errorf("read input: %w", err)
+			}
+			return "", fmt.Errorf("no selection provided")
+		}
+		text := strings.TrimSpace(scanner.Text())
+		if text == "" {
+			continue
+		}
+		if idx, err := strconv.Atoi(text); err == nil {
+			if idx < 1 || idx > len(entries) {
+				fmt.Fprintf(stdout, "Out of range. Enter 1-%d.\n", len(entries))
+				continue
+			}
+			return entries[idx-1].ID, nil
+		}
+		for _, m := range entries {
+			if m.ID == text {
+				return m.ID, nil
+			}
+		}
+		fmt.Fprintln(stdout, "Not a valid number or model id; try again.")
+	}
+}
+
+func upsertModelDefault(apiBase, apiKey, alias, modelID string, stdout io.Writer) error {
+	configPath := internal.GetConfigPath()
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		return fmt.Errorf("failed to load config: %w", err)
+	}
+
+	secureKeys := config.SimpleSecureStrings(apiKey)
+
+	found := false
+	for _, m := range cfg.ModelList {
+		if m == nil {
+			continue
+		}
+		if m.ModelName == alias {
+			m.Model = modelID
+			m.APIBase = apiBase
+			m.APIKeys = secureKeys
+			m.Enabled = true
+			found = true
+			break
+		}
+	}
+	if !found {
+		cfg.ModelList = append(cfg.ModelList, &config.ModelConfig{
+			ModelName: alias,
+			Model:     modelID,
+			APIBase:   apiBase,
+			APIKeys:   secureKeys,
+			Enabled:   true,
+		})
+	}
+
+	cfg.Agents.Defaults.ModelName = alias
+
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	fmt.Fprintf(stdout, "✓ Saved model '%s' (%s) and set as default.\n", alias, modelID)
+	return nil
+}

cmd/picoclaw/internal/model/add_test.go

@@ -0,0 +1,257 @@
+package model
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestFetchOpenAIModels_DataEnvelope(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/models", r.URL.Path)
+		assert.Equal(t, "Bearer secret", r.Header.Get("Authorization"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"data":[{"id":"gpt-foo","name":"Foo"},{"id":"gpt-bar"}]}`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "secret")
+	require.NoError(t, err)
+	require.Len(t, entries, 2)
+	assert.Equal(t, "gpt-foo", entries[0].ID)
+	assert.Equal(t, "Foo", entries[0].Name)
+	assert.Equal(t, "gpt-bar", entries[1].ID)
+}
+
+func TestFetchOpenAIModels_BareArray(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":"a"},{"id":"b"}]`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "secret")
+	require.NoError(t, err)
+	require.Len(t, entries, 2)
+	assert.Equal(t, "a", entries[0].ID)
+	assert.Equal(t, "b", entries[1].ID)
+}
+
+func TestFetchOpenAIModels_TrimsTrailingSlash(t *testing.T) {
+	var gotPath string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		_, _ = w.Write([]byte(`{"data":[{"id":"x"}]}`))
+	}))
+	defer srv.Close()
+
+	_, err := fetchOpenAIModels(srv.URL+"/", "k")
+	require.NoError(t, err)
+	assert.Equal(t, "/models", gotPath)
+}
+
+func TestFetchOpenAIModels_HTTPError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "nope", http.StatusUnauthorized)
+	}))
+	defer srv.Close()
+
+	_, err := fetchOpenAIModels(srv.URL, "bad")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "HTTP 401")
+}
+
+func TestFetchOpenAIModels_EmptyDataEnvelope(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"data":[]}`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "k")
+	require.NoError(t, err)
+	assert.Empty(t, entries)
+}
+
+func TestFetchOpenAIModels_EmptyBareArray(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`[]`))
+	}))
+	defer srv.Close()
+
+	entries, err := fetchOpenAIModels(srv.URL, "k")
+	require.NoError(t, err)
+	assert.Empty(t, entries)
+}
+
+func TestFetchOpenAIModels_UnrecognizedShape(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"models":"not-supported"}`))
+	}))
+	defer srv.Close()
+
+	_, err := fetchOpenAIModels(srv.URL, "k")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unrecognized shape")
+}
+
+func TestFetchOpenAIModels_RequiresInputs(t *testing.T) {
+	_, err := fetchOpenAIModels("", "k")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "api base")
+
+	_, err = fetchOpenAIModels("https://example.com", "")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "api key")
+}
+
+func TestPickModel_ByIndex(t *testing.T) {
+	entries := []modelEntry{{ID: "a"}, {ID: "b"}, {ID: "c"}}
+	out := &bytes.Buffer{}
+	got, err := pickModel(strings.NewReader("2\n"), out, entries)
+	require.NoError(t, err)
+	assert.Equal(t, "b", got)
+	assert.Contains(t, out.String(), "3 model(s) available")
+}
+
+func TestPickModel_ByID(t *testing.T) {
+	entries := []modelEntry{{ID: "alpha"}, {ID: "beta"}}
+	out := &bytes.Buffer{}
+	got, err := pickModel(strings.NewReader("beta\n"), out, entries)
+	require.NoError(t, err)
+	assert.Equal(t, "beta", got)
+}
+
+func TestPickModel_RetriesOnInvalid(t *testing.T) {
+	entries := []modelEntry{{ID: "x"}}
+	out := &bytes.Buffer{}
+	got, err := pickModel(strings.NewReader("\n9\nnot-a-model\nx\n"), out, entries)
+	require.NoError(t, err)
+	assert.Equal(t, "x", got)
+	rendered := out.String()
+	assert.Contains(t, rendered, "Out of range")
+	assert.Contains(t, rendered, "Not a valid number")
+}
+
+func TestRunAdd_WithExplicitModel_NoNetwork(t *testing.T) {
+	initTest(t)
+
+	out := &bytes.Buffer{}
+	err := runAdd(addOptions{
+		apiBase:   "https://invalid.invalid/v1",
+		apiKey:    "k",
+		modelID:   "explicit-model",
+		alias:     "myalias",
+		modelType: "openai-compatible",
+		stdout:    out,
+	})
+	require.NoError(t, err)
+	assert.Contains(t, out.String(), "Saved model 'myalias' (explicit-model)")
+
+	cfg, err := config.LoadConfig(configPath)
+	require.NoError(t, err)
+	assert.Equal(t, "myalias", cfg.Agents.Defaults.GetModelName())
+	added := findModelByName(cfg, "myalias")
+	require.NotNil(t, added, "expected model 'myalias' in model_list")
+	assert.Equal(t, "explicit-model", added.Model)
+	assert.Equal(t, "https://invalid.invalid/v1", added.APIBase)
+	assert.True(t, added.Enabled)
+	require.Len(t, added.APIKeys, 1)
+	assert.Equal(t, "k", added.APIKeys[0].String())
+}
+
+func findModelByName(cfg *config.Config, name string) *config.ModelConfig {
+	for _, m := range cfg.ModelList {
+		if m != nil && m.ModelName == name {
+			return m
+		}
+	}
+	return nil
+}
+
+func TestRunAdd_FetchAndPick(t *testing.T) {
+	initTest(t)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "Bearer my-key", r.Header.Get("Authorization"))
+		_, _ = w.Write([]byte(`{"data":[{"id":"m1"},{"id":"m2"}]}`))
+	}))
+	defer srv.Close()
+
+	out := &bytes.Buffer{}
+	err := runAdd(addOptions{
+		apiBase:   srv.URL,
+		apiKey:    "my-key",
+		alias:     defaultAliasName,
+		modelType: "openai-compatible",
+		stdin:     strings.NewReader("2\n"),
+		stdout:    out,
+	})
+	require.NoError(t, err)
+
+	cfg, err := config.LoadConfig(configPath)
+	require.NoError(t, err)
+	assert.Equal(t, defaultAliasName, cfg.Agents.Defaults.GetModelName())
+	added := findModelByName(cfg, defaultAliasName)
+	require.NotNil(t, added)
+	assert.Equal(t, "m2", added.Model)
+}
+
+func TestRunAdd_UpsertsExistingAlias(t *testing.T) {
+	initTest(t)
+
+	first := &bytes.Buffer{}
+	require.NoError(t, runAdd(addOptions{
+		apiBase: "https://a.example/v1",
+		apiKey:  "k1",
+		modelID: "m1",
+		alias:   "shared",
+		stdout:  first,
+	}))
+
+	second := &bytes.Buffer{}
+	require.NoError(t, runAdd(addOptions{
+		apiBase: "https://b.example/v1",
+		apiKey:  "k2",
+		modelID: "m2",
+		alias:   "shared",
+		stdout:  second,
+	}))
+
+	cfg, err := config.LoadConfig(configPath)
+	require.NoError(t, err)
+	matches := 0
+	for _, m := range cfg.ModelList {
+		if m != nil && m.ModelName == "shared" {
+			matches++
+		}
+	}
+	assert.Equal(t, 1, matches, "alias should be updated, not duplicated")
+
+	updated := findModelByName(cfg, "shared")
+	require.NotNil(t, updated)
+	assert.Equal(t, "m2", updated.Model)
+	assert.Equal(t, "https://b.example/v1", updated.APIBase)
+	assert.Equal(t, "k2", updated.APIKeys[0].String())
+}
+
+func TestRunAdd_RejectsUnsupportedType(t *testing.T) {
+	initTest(t)
+
+	err := runAdd(addOptions{
+		apiBase:   "https://x/v1",
+		apiKey:    "k",
+		modelID:   "m",
+		alias:     "a",
+		modelType: "anthropic",
+		stdout:    &bytes.Buffer{},
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unsupported --type")
+}

cmd/picoclaw/internal/model/command.go

@@ -21,11 +21,17 @@ func NewModelCommand() *cobra.Command {
 If no argument is provided, shows the current default model.
 If a model name is provided, sets it as the default model.
 
+To onboard a model from a custom OpenAI-compatible endpoint (fetch the
+available list online and pick one), use the 'add' subcommand:
+
+  picoclaw model add --help
+
 Examples:
   picoclaw model                    # Show current default model
   picoclaw model gpt-5.2           # Set gpt-5.2 as default
   picoclaw model claude-sonnet-4.6 # Set claude-sonnet-4.6 as default
   picoclaw model local-model       # Set local VLLM server as default
+  picoclaw model add -b URL -k KEY # Add a model from a custom endpoint
 
 Note: 'local-model' is a special value for using a local VLLM server
 (running at localhost:8000 by default) which does not require an API key.`,
@@ -51,6 +57,8 @@ Note: 'local-model' is a special value for using a local VLLM server
 		},
 	}
 
+	cmd.AddCommand(newAddCommand())
+
 	return cmd
 }
 
@@ -66,6 +74,9 @@ func showCurrentModel(cfg *config.Config) {
 		fmt.Println("\nAvailable models in your config:")
 		listAvailableModels(cfg)
 	}
+
+	fmt.Println("\nTip: 'picoclaw model add -b URL -k KEY' adds a model from a custom")
+	fmt.Println("     OpenAI-compatible endpoint (see 'picoclaw model add --help').")
 }
 
 func listAvailableModels(cfg *config.Config) {

cmd/picoclaw/internal/model/online.go

@@ -0,0 +1,77 @@
+package model
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+type modelEntry struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+type modelsAPIResponse struct {
+	Data []modelEntry `json:"data"`
+}
+
+// fetchOpenAIModels GETs <baseURL>/models with Bearer auth and accepts both the
+// {data:[…]} envelope and a bare array shape used by various OpenAI-compatible servers.
+func fetchOpenAIModels(baseURL, apiKey string) ([]modelEntry, error) {
+	if strings.TrimSpace(baseURL) == "" {
+		return nil, fmt.Errorf("api base is required")
+	}
+	if strings.TrimSpace(apiKey) == "" {
+		return nil, fmt.Errorf("api key is required")
+	}
+
+	url := strings.TrimRight(baseURL, "/") + "/models"
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("build request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+apiKey)
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	// {"data": [...]} envelope. Distinguish "envelope shape with empty list"
+	// from "object without a data key" via Data being non-nil after unmarshal:
+	// json.Unmarshal sets Data to []modelEntry{} for `{"data":[]}` but leaves
+	// it as nil when "data" is absent or null.
+	var envelope modelsAPIResponse
+	if err := json.Unmarshal(body, &envelope); err == nil && envelope.Data != nil {
+		return envelope.Data, nil
+	}
+
+	// Bare-array shape, including `[]`.
+	var arr []modelEntry
+	if err := json.Unmarshal(body, &arr); err == nil {
+		return arr, nil
+	}
+
+	preview := body
+	if len(preview) > 256 {
+		preview = preview[:256]
+	}
+	return nil, fmt.Errorf("decode response: unrecognized shape: %s", strings.TrimSpace(string(preview)))
+}

cmd/picoclaw/internal/onboard/command.go

@@ -6,7 +6,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-//go:generate cp -r ../../../../workspace .
+//go:generate go run ../../../../scripts/copydir.go ../../../../workspace ./workspace
 //go:embed workspace
 var embeddedFiles embed.FS
 

cmd/picoclaw/main.go

@@ -19,6 +19,7 @@ import (
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cliui"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cron"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/gateway"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/mcp"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/migrate"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/model"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/onboard"
@@ -87,6 +88,7 @@ picoclaw --no-color status`,
 		gateway.NewGatewayCommand(),
 		status.NewStatusCommand(),
 		cron.NewCronCommand(),
+		mcp.NewMCPCommand(),
 		migrate.NewMigrateCommand(),
 		skills.NewSkillsCommand(),
 		model.NewModelCommand(),

cmd/picoclaw/main_test.go

@@ -41,6 +41,7 @@ func TestNewPicoclawCommand(t *testing.T) {
 		"auth",
 		"cron",
 		"gateway",
+		"mcp",
 		"migrate",
 		"model",
 		"onboard",

config/config.example.json

@@ -13,7 +13,8 @@
       "split_on_marker": false,
       "tool_feedback": {
         "enabled": false,
-        "max_args_length": 300
+        "max_args_length": 300,
+        "separate_messages": false
       }
     }
   },
@@ -436,6 +437,9 @@
       "enabled": true,
       "mode": "bytes"
     },
+    "serial": {
+      "enabled": false
+    },
     "send_tts": {
       "enabled": false
     },

docker/Dockerfile.full

@@ -1,7 +1,7 @@
 # ============================================================
 # Stage 1: Build the picoclaw binary
 # ============================================================
-FROM golang:1.26.0-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 RUN apk add --no-cache git make
 

docker/Dockerfile.goreleaser.launcher

@@ -6,7 +6,6 @@ RUN apk add --no-cache ca-certificates tzdata
 
 COPY $TARGETPLATFORM/picoclaw /usr/local/bin/picoclaw
 COPY $TARGETPLATFORM/picoclaw-launcher /usr/local/bin/picoclaw-launcher
-COPY $TARGETPLATFORM/picoclaw-launcher-tui /usr/local/bin/picoclaw-launcher-tui
 
 ENTRYPOINT ["picoclaw-launcher"]
 CMD ["-console", "-public", "-no-browser"]

docker/Dockerfile.heavy

@@ -1,7 +1,7 @@
 # ============================================================
 # Stage 1: Build the picoclaw binary
 # ============================================================
-FROM golang:1.26.0-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 RUN apk add --no-cache git make
 

docker/Dockerfile.launcher

@@ -0,0 +1,65 @@
+# ============================================================
+# Stage 1: Build frontend assets (Node.js + pnpm)
+# ============================================================
+FROM node:24-alpine3.23 AS frontend
+
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
+WORKDIR /src/web/frontend
+
+# Cache frontend dependencies
+COPY web/frontend/package.json web/frontend/pnpm-lock.yaml ./
+RUN CI=true pnpm install --frozen-lockfile
+
+# Build frontend
+COPY web/frontend/ ./
+RUN pnpm build:backend
+
+# ============================================================
+# Stage 2: Build Go binaries (picoclaw + picoclaw-launcher)
+# ============================================================
+FROM golang:1.25-alpine AS builder
+
+RUN apk add --no-cache git make
+
+WORKDIR /src
+
+# Cache Go dependencies
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source
+COPY . .
+
+# Copy pre-built frontend assets into the backend embed directory
+COPY --from=frontend /src/web/backend/dist web/backend/dist
+
+# Build picoclaw binary (includes go generate)
+RUN make build
+
+# Build picoclaw-launcher binary (frontend already built in stage 1)
+# Mirror ldflags from web/Makefile to inject version metadata
+RUN CONFIG_PKG=github.com/sipeed/picoclaw/pkg/config && \
+    VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo dev) && \
+    GIT_COMMIT=$(git rev-parse --short=8 HEAD 2>/dev/null || echo dev) && \
+    BUILD_TIME=$(date +%FT%T%z) && \
+    GO_VERSION=$(go env GOVERSION) && \
+    CGO_ENABLED=0 go build -v -tags goolm,stdjson \
+      -ldflags "-X ${CONFIG_PKG}.Version=${VERSION} -X ${CONFIG_PKG}.GitCommit=${GIT_COMMIT} -X ${CONFIG_PKG}.BuildTime=${BUILD_TIME} -X ${CONFIG_PKG}.GoVersion=${GO_VERSION} -s -w" \
+      -o build/picoclaw-launcher ./web/backend/
+
+# ============================================================
+# Stage 3: Minimal runtime image
+# ============================================================
+FROM alpine:3.23
+
+RUN apk add --no-cache ca-certificates tzdata curl
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget -q --spider http://localhost:18790/health || exit 1
+
+COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
+COPY --from=builder /src/build/picoclaw-launcher /usr/local/bin/picoclaw-launcher
+
+ENTRYPOINT ["picoclaw-launcher"]
+CMD ["-console", "-public", "-no-browser"]

docker/docker-compose.yml

@@ -4,6 +4,9 @@ services:
   #   docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Hello"
   # ─────────────────────────────────────────────
   picoclaw-agent:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
     image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-agent
     profiles:
@@ -22,6 +25,9 @@ services:
   #   docker compose -f docker/docker-compose.yml --profile gateway up
   # ─────────────────────────────────────────────
   picoclaw-gateway:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
     image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-gateway
     restart: unless-stopped
@@ -38,6 +44,9 @@ services:
   #   docker compose -f docker/docker-compose.yml --profile launcher up
   # ─────────────────────────────────────────────
   picoclaw-launcher:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.launcher
     image: docker.io/sipeed/picoclaw:launcher
     container_name: picoclaw-launcher
     restart: unless-stopped

docker/entrypoint.sh

@@ -12,4 +12,10 @@ if [ ! -d "${HOME}/.picoclaw/workspace" ] && [ ! -f "${HOME}/.picoclaw/config.js
     exit 0
 fi
 
+# Remove stale PID file from a previous container run.
+# After docker kill / OOM / crash the PID file may linger on the bind-mounted
+# volume and block the next gateway start (the recorded PID could collide with
+# an unrelated process inside the new container).
+rm -f "${HOME}/.picoclaw/.picoclaw.pid"
+
 exec picoclaw gateway "$@"

docs/design/current-hardware-support-and-serial.zh.md

@@ -0,0 +1,91 @@
+# 当前硬件支持现状与串口 Tool 方案
+
+## 现状结论
+
+当前项目已有的硬件相关能力主要分为两条线：
+
+1. 设备事件监控
+   - `pkg/devices` 已实现设备事件服务。
+   - 当前只有 Linux USB 热插拔事件源 `pkg/devices/sources/usb_linux.go`。
+   - 能力定位是“发现和通知”，不是“总线读写控制”。
+
+2. 硬件控制 Tool
+   - `pkg/tools/hardware/i2c*.go`：I2C Tool，支持 `detect`、`scan`、`read`、`write`。
+   - `pkg/tools/hardware/spi*.go`：SPI Tool，支持 `list`、`transfer`、`read`。
+   - 这两类 Tool 当前都只在 Linux 主机上启用，直接依赖 `/dev/i2c-*` 与 `/dev/spidev*`。
+
+因此，项目在“硬件支持能力”上已经具备：
+
+- Linux USB 设备插拔感知
+- Linux I2C 总线控制
+- Linux SPI 总线控制
+
+但还缺少：
+
+- 串口/UART 控制
+- macOS / Windows 下可直接使用的硬件控制 Tool
+- 面向统一硬件抽象的跨总线能力模型
+
+## 本次新增
+
+本次新增内建 `serial` Tool，并接入现有 Tool 体系：
+
+- 配置项：`tools.serial.enabled`
+- Tool 注册：`pkg/agent/agent_init.go`
+- Web 工具页：`/api/tools` 能展示与切换 `serial`
+- 前端状态文案：新增 `requires_serial_platform`
+
+## Serial Tool 设计
+
+`serial` 采用无状态调用模型，每次请求都自行打开和关闭端口，避免在 agent 回合之间维护串口会话状态。
+
+支持动作：
+
+- `list`：枚举主机串口
+- `read`：从串口读取指定长度字节
+- `write`：向串口写入字节或文本
+
+公共参数：
+
+- `port`
+- `baud`
+- `data_bits`
+- `parity`
+- `stop_bits`
+- `timeout_ms`
+
+当前波特率实现边界：
+
+- Windows 允许配置工具层接受的范围 `50-4000000`
+- Linux / macOS 当前仅支持标准 termios 波特率，实际支持到 `230400`
+- 因此 `baud` 的跨平台可移植取值应优先使用 `230400` 及以下的常见标准速率
+
+安全约束：
+
+- `write` 必须显式传 `confirm: true`
+- 单次读写负载限制为 `4096` 字节
+- `port` 只接受白名单串口名：
+  - Linux / macOS 仅允许 `/dev/tty*`、`/dev/cu.*` 及对应简写设备名
+  - Windows 仅允许 `COM\d+` 或 `\\.\COM\d+`
+  - 明确拒绝 `..`、普通文件绝对路径、盘符路径等非串口设备路径，避免路径穿越或误打开任意文件
+
+## 跨平台实现边界
+
+- Linux / macOS：
+  - 基于 `golang.org/x/sys/unix` 和 termios 配置串口参数。
+  - 当前仅接入标准 termios 波特率映射，最高到 `230400`，尚未扩展 `460800`、`921600`、`1000000`、`2000000` 等更高速率。
+  - 通过 `/dev/...` 枚举和访问设备。
+
+- Windows：
+  - 基于 `kernel32` 串口 API 配置 `DCB` 和 `COMMTIMEOUTS`。
+  - 当前读写仍使用同步 `ReadFile` / `WriteFile`；一旦 syscall 已进入执行，turn context cancellation 不能立即打断，只能等待 `COMMTIMEOUTS` 触发后返回。
+  - 通过注册表 `HARDWARE\\DEVICEMAP\\SERIALCOMM` 枚举端口。
+
+- 其他平台：
+  - `serial` Tool 显式返回 unsupported，不做静默降级。
+
+## 后续建议
+
+1. 如果需要持续交互式串口会话，建议再增加 session 型 Tool，而不是让 LLM 反复做短连接轮询。
+2. 如果后续要支持 CAN、GPIO、PWM，建议抽出统一的硬件 capability 描述层，而不是继续只靠 Tool 名称区分。
+3. 若需要生产级稳定性，建议补真实串口回环测试，至少覆盖 Linux PTY 和 Windows COM 模拟场景。

docs/guides/docker.fr.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Mode Launcher (Console Web)
 
-L'image `launcher` inclut les trois binaires (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) et démarre la console web par défaut, qui fournit une interface navigateur pour la configuration et le chat.
+L'image `launcher` inclut les deux binaires (`picoclaw`, `picoclaw-launcher`) et démarre la console web par défaut, qui fournit une interface navigateur pour la configuration et le chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.ja.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Launcher モード (Web コンソール)
 
-`launcher` イメージには 3 つのバイナリ（`picoclaw`、`picoclaw-launcher`、`picoclaw-launcher-tui`）がすべて含まれており、デフォルトで Web コンソールを起動します。ブラウザベースの設定・チャット画面を提供します。
+`launcher` イメージには 2 つのバイナリ（`picoclaw`、`picoclaw-launcher`）が含まれており、デフォルトで Web コンソールを起動します。ブラウザベースの設定・チャット画面を提供します。
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.md

@@ -39,7 +39,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Launcher Mode (Web Console)
 
-The `launcher` image includes all three binaries (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) and starts the web console by default, which provides a browser-based UI for configuration and chat.
+The `launcher` image includes both binaries (`picoclaw`, `picoclaw-launcher`) and starts the web console by default, which provides a browser-based UI for configuration and chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.ms.md

@@ -35,7 +35,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Mod Launcher (Konsol Web)
 
-Imej `launcher` merangkumi ketiga-tiga binari (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) dan memulakan konsol web secara lalai, yang menyediakan UI berasaskan pelayar untuk konfigurasi dan sembang.
+Imej `launcher` merangkumi kedua-dua binari (`picoclaw`, `picoclaw-launcher`) dan memulakan konsol web secara lalai, yang menyediakan UI berasaskan pelayar untuk konfigurasi dan sembang.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.pt-br.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Modo Launcher (Console Web)
 
-A imagem `launcher` inclui os três binários (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) e inicia o console web por padrão, que fornece uma interface baseada em navegador para configuração e chat.
+A imagem `launcher` inclui ambos os binários (`picoclaw`, `picoclaw-launcher`) e inicia o console web por padrão, que fornece uma interface baseada em navegador para configuração e chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.vi.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Chế Độ Launcher (Web Console)
 
-Image `launcher` bao gồm cả ba binary (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) và khởi động web console mặc định, cung cấp giao diện trình duyệt để cấu hình và chat.
+Image `launcher` bao gồm cả hai binary (`picoclaw`, `picoclaw-launcher`) và khởi động web console mặc định, cung cấp giao diện trình duyệt để cấu hình và chat.
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/guides/docker.zh.md

@@ -36,7 +36,7 @@ docker compose -f docker/docker-compose.yml --profile gateway down
 
 ### Launcher 模式 (Web 控制台)
 
-`launcher` 镜像包含所有三个二进制文件（`picoclaw`、`picoclaw-launcher`、`picoclaw-launcher-tui`），默认启动 Web 控制台，提供基于浏览器的配置和聊天界面。
+`launcher` 镜像包含两个二进制文件（`picoclaw`、`picoclaw-launcher`），默认启动 Web 控制台，提供基于浏览器的配置和聊天界面。
 
 ```bash
 docker compose -f docker/docker-compose.yml --profile launcher up -d

docs/operations/debug.md

@@ -65,7 +65,8 @@ Debug logs are server-side only. If you want the agent to send a visible notific
     "defaults": {
       "tool_feedback": {
         "enabled": true,
-        "max_args_length": 300
+        "max_args_length": 300,
+        "separate_messages": true
       }
     }
   }
@@ -85,6 +86,7 @@ When `enabled` is `true`, every tool call sends a short message to the chat befo
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | bool | `false` | Send a chat notification for each tool call |
+| `separate_messages` | bool | `false` | Keep every tool feedback update as a separate chat message instead of reusing a single placeholder/progress message |
 | `max_args_length` | int | `300` | Maximum characters of the serialised arguments included in the notification |
 
 ### Environment variables

docs/project/README.fr.md

@@ -292,24 +292,6 @@ Après cette étape unique, `picoclaw-launcher` s'ouvrira normalement lors des l
 
 </details>
 
-### 💻 TUI Launcher (Recommandé pour les environnements sans interface / SSH)
-
-Le TUI (Terminal UI) Launcher fournit une interface terminal complète pour la configuration et la gestion. Idéal pour les serveurs, Raspberry Pi et autres environnements sans interface graphique.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Pour commencer :**
-
-Utilisez les menus TUI pour : **1)** Configurer un Provider -> **2)** Configurer un Channel -> **3)** Démarrer le Gateway -> **4)** Chattez !
-
-Pour la documentation détaillée du TUI, voir [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.id.md

@@ -289,24 +289,6 @@ Setelah langkah satu kali ini, `picoclaw-launcher` akan terbuka secara normal pa
 
 </details>
 
-### 💻 TUI Launcher (Direkomendasikan untuk Headless / SSH)
-
-TUI (Terminal UI) Launcher menyediakan antarmuka terminal lengkap untuk konfigurasi dan manajemen. Ideal untuk server, Raspberry Pi, dan lingkungan headless lainnya.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Memulai:**
-
-Gunakan menu TUI untuk: **1)** Konfigurasi Provider -> **2)** Konfigurasi Channel -> **3)** Mulai Gateway -> **4)** Chat!
-
-Untuk dokumentasi TUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
-
 ### 📱 Android
 
 Berikan kehidupan kedua untuk ponsel lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw.

docs/project/README.it.md

@@ -289,24 +289,6 @@ Dopo questo passaggio una tantum, `picoclaw-launcher` si aprirà normalmente ai
 
 </details>
 
-### 💻 TUI Launcher (Consigliato per Headless / SSH)
-
-Il TUI (Terminal UI) Launcher fornisce un'interfaccia terminale completa per la configurazione e la gestione. Ideale per server, Raspberry Pi e altri ambienti headless.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Per iniziare:**
-
-Usa i menu TUI per: **1)** Configurare un Provider -> **2)** Configurare un Channel -> **3)** Avviare il Gateway -> **4)** Chattare!
-
-Per la documentazione dettagliata del TUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io).
-
 ### 📱 Android
 
 Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw.
@@ -554,7 +536,20 @@ PicoClaw supporta nativamente [MCP](https://modelcontextprotocol.io/) — connet
 }
 ```
 
-Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](../reference/tools_configuration.md#mcp-tool).
+Puoi gestire i casi MCP più comuni direttamente dalla CLI senza modificare a mano il JSON:
+
+```bash
+picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
+picoclaw mcp list
+picoclaw mcp test filesystem
+```
+
+`picoclaw mcp` agisce come configuration manager: aggiorna `config.json` sotto `tools.mcp.servers`, ma non mantiene in esecuzione il processo del server.
+
+Usa `picoclaw mcp edit` quando ti servono campi avanzati che non sono coperti da `picoclaw mcp add`.
+Per esempio, `picoclaw mcp add` supporta `--deferred` e `--env-file`, mentre `picoclaw mcp edit` resta utile per modifiche JSON dirette e opzioni MCP meno comuni.
+
+Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](../reference/tools_configuration.md#mcp-tool). Per la reference della CLI, vedi [MCP Server CLI](../reference/mcp-cli.md).
 
 ## <img src="../../assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Unisciti al Social Network degli Agent
 
@@ -574,6 +569,11 @@ Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singol
 | `picoclaw status`         | Mostra lo stato                    |
 | `picoclaw version`        | Mostra le info sulla versione      |
 | `picoclaw model`          | Visualizza o cambia il modello predefinito |
+| `picoclaw mcp list`       | Elenca i server MCP configurati    |
+| `picoclaw mcp add ...`    | Aggiunge o aggiorna un server MCP  |
+| `picoclaw mcp test`       | Verifica la raggiungibilità di un server MCP |
+| `picoclaw mcp edit`       | Apre la config per modifiche MCP avanzate |
+| `picoclaw mcp remove`     | Rimuove un server MCP dalla config |
 | `picoclaw cron list`      | Elenca tutti i job pianificati     |
 | `picoclaw cron add ...`   | Aggiunge un job pianificato        |
 | `picoclaw cron disable`   | Disabilita un job pianificato      |
@@ -600,6 +600,7 @@ Per guide dettagliate oltre questo README:
 | [Docker & Avvio Rapido](../guides/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent |
 | [App di Chat](../guides/chat-apps.md) | Tutte le guide di configurazione per 17+ channel |
 | [Configurazione](../guides/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza |
+| [MCP Server CLI](../reference/mcp-cli.md) | Aggiunta, elenco, test, modifica e rimozione dei server MCP da CLI |
 | [Provider & Modelli](../guides/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list |
 | [Spawn & Task Asincroni](../guides/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
 | [Hooks](../architecture/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook |

docs/project/README.ja.md

@@ -289,24 +289,6 @@ docker compose -f docker/docker-compose.yml --profile launcher up -d
 
 </details>
 
-### 💻 TUI Launcher（ヘッドレス / SSH 向け推奨）
-
-TUI（Terminal UI）Launcher は設定と管理のためのフル機能ターミナルインターフェースを提供します。サーバー、Raspberry Pi、その他のヘッドレス環境に最適です。
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**始め方:**
-
-TUI メニューを使って：**1)** Provider を設定 → **2)** Channel を設定 → **3)** Gateway を起動 → **4)** チャット！
-
-TUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.ko.md

@@ -289,24 +289,6 @@ macOS에서는 인터넷에서 다운로드한 앱이고 Mac App Store 공증을
 
 </details>
 
-### 💻 TUI Launcher (헤드리스 / SSH 권장)
-
-TUI(Terminal UI) Launcher는 설정과 관리를 위한 모든 기능을 갖춘 터미널 인터페이스를 제공합니다. 서버, Raspberry Pi, 기타 헤드리스 환경에 적합합니다.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**시작 방법:**
-
-TUI 메뉴를 사용해 다음 순서로 진행하세요. **1)** 프로바이더 설정 -> **2)** 채널 설정 -> **3)** 게이트웨이 시작 -> **4)** 채팅!
-
-자세한 TUI 문서는 [docs.picoclaw.io](https://docs.picoclaw.io)를 참고하세요.
-
 ### 📱 Android
 
 오래된 스마트폰에 새 생명을 불어넣어 보세요! PicoClaw를 설치하면 스마트 AI 어시스턴트로 바꿀 수 있습니다.

docs/project/README.ms.md

@@ -286,24 +286,6 @@ Selepas langkah sekali ini, `picoclaw-launcher` akan dibuka secara normal pada p
 
 </details>
 
-### 💻 Pelancar TUI (Disyorkan untuk Headless / SSH)
-
-Pelancar TUI menyediakan antara muka terminal lengkap untuk konfigurasi dan pengurusan. Sesuai untuk pelayan, Raspberry Pi, dan persekitaran tanpa kepala lain.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="Pelancar TUI" width="600">
-</p>
-
-**Memulakan:**
-
-Gunakan menu TUI untuk: **1)** Konfigurasikan Penyedia -> **2)** Konfigurasikan Saluran -> **3)** Mulakan Gateway -> **4)** Sembang!
-
-Untuk dokumentasi TUI terperinci, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
-
 ### 📱 Android
 
 Berikan telefon lama anda kehidupan baru! Jadikannya Pembantu AI pintar dengan PicoClaw.

docs/project/README.pt-br.md

@@ -289,24 +289,6 @@ Após esta etapa única, o `picoclaw-launcher` abrirá normalmente nos lançamen
 
 </details>
 
-### 💻 TUI Launcher (Recomendado para Headless / SSH)
-
-O TUI (Terminal UI) Launcher fornece uma interface de terminal completa para configuração e gerenciamento. Ideal para servidores, Raspberry Pi e outros ambientes headless.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Primeiros passos:**
-
-Use os menus do TUI para: **1)** Configurar um Provider -> **2)** Configurar um Channel -> **3)** Iniciar o Gateway -> **4)** Conversar!
-
-Para documentação detalhada do TUI, veja [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.vi.md

@@ -289,24 +289,6 @@ Sau bước này, `picoclaw-launcher` sẽ mở bình thường trong các lần
 
 </details>
 
-### 💻 TUI Launcher (Khuyến nghị cho Headless / SSH)
-
-TUI (Terminal UI) Launcher cung cấp giao diện terminal đầy đủ tính năng để cấu hình và quản lý. Lý tưởng cho máy chủ, Raspberry Pi và các môi trường headless khác.
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**Bắt đầu:**
-
-Sử dụng menu TUI để: **1)** Cấu hình Provider -> **2)** Cấu hình Channel -> **3)** Khởi động Gateway -> **4)** Trò chuyện!
-
-Để biết tài liệu TUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io).
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/project/README.zh.md

@@ -289,24 +289,6 @@ macOS 可能会在首次启动时拦截 `picoclaw-launcher`，因为它从互联
 
 </details>
 
-### 💻 TUI Launcher（推荐无头环境 / SSH）
-
-TUI（终端 UI）Launcher 提供功能完整的终端配置与管理界面，适合服务器、树莓派等无显示器环境。
-
-```bash
-picoclaw-launcher-tui
-```
-
-<p align="center">
-<img src="../../assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
-</p>
-
-**开始使用：**
-
-通过 TUI 菜单：**1)** 配置 Provider -> **2)** 配置 Channel -> **3)** 启动 Gateway -> **4)** 开始聊天！
-
-详细 TUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。
-
 <a id="-run-on-old-android-phones"></a>
 ### 📱 Android
 

docs/reference/README.md

@@ -3,6 +3,7 @@
 Reference docs for precise configuration, runtime behavior, and tool semantics.
 
 - [Tools Configuration](tools_configuration.md): per-tool configuration, execution policies, MCP, and Skills.
+- [MCP Server CLI](mcp-cli.md): add, list, test, edit, and remove MCP server entries from the command line.
 - [Scheduled Tasks and Cron Jobs](cron.md): schedule types, delivery modes, command gates, and storage.
 - [Config Schema Versioning Guide](config-versioning.md): config schema migration and compatibility notes.
 - [Dynamic Rate Limiting](rate-limiting.md): request throttling behavior for LLM providers.

docs/reference/mcp-cli.md

@@ -0,0 +1,361 @@
+# MCP Server CLI
+
+> Back to [README](../README.md)
+
+PicoClaw includes an `mcp` CLI command group for managing MCP server entries in `config.json`.
+
+This CLI acts as a **configuration manager**:
+
+- it adds, updates, removes, and validates entries under `tools.mcp.servers`
+- it does **not** keep MCP servers running itself
+- the gateway / host still starts the configured servers when MCP is enabled
+
+## Where It Writes
+
+The CLI updates the same config file used by the rest of PicoClaw:
+
+- `PICOCLAW_CONFIG` if set
+- otherwise `~/.picoclaw/config.json`
+
+When the CLI writes the file, it:
+
+- saves atomically
+- preserves the standard 2-space JSON formatting used by PicoClaw
+- validates the generated JSON before writing
+
+Behavior notes:
+
+- `picoclaw mcp add ...` enables `tools.mcp.enabled`
+- removing the last server with `picoclaw mcp remove ...` disables `tools.mcp.enabled`
+
+## Quick Start
+
+Add a stdio server via `npx`:
+
+```bash
+picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+Add a stdio server with environment variables saved in config:
+
+```bash
+picoclaw mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github
+```
+
+Add a stdio server using an env file for secrets:
+
+```bash
+picoclaw mcp add github --env-file .env.github -- npx -y @modelcontextprotocol/server-github
+```
+
+Add a remote HTTP server:
+
+```bash
+picoclaw mcp add context7 --transport http https://mcp.context7.com/mcp
+```
+
+Add a remote HTTP server with auth header, even with flags after the URL:
+
+```bash
+picoclaw mcp add apify "https://mcp.apify.com/" -t http --header "Authorization: Bearer OMITTED"
+```
+
+Add a stdio server using an explicit command separator:
+
+```bash
+picoclaw mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server
+```
+
+Inspect the configured entries:
+
+```bash
+picoclaw mcp list
+picoclaw mcp list --status
+```
+
+Inspect one server's full details and its exposed tools:
+
+```bash
+picoclaw mcp show filesystem
+```
+
+Probe a single server entry:
+
+```bash
+picoclaw mcp test filesystem
+```
+
+Open the raw config for advanced editing:
+
+```bash
+picoclaw mcp edit
+```
+
+## Command Summary
+
+| Command | Purpose |
+|---------|---------|
+| `picoclaw mcp add <name> [flags] <command-or-url> [args...]` | Add or update an MCP server entry |
+| `picoclaw mcp remove <name>` | Remove a server entry from config |
+| `picoclaw mcp list` | List configured MCP servers |
+| `picoclaw mcp show <name>` | Show full details and tools for one server |
+| `picoclaw mcp test <name>` | Try connecting to one configured server |
+| `picoclaw mcp edit` | Open `config.json` in `$EDITOR` |
+
+## `picoclaw mcp add`
+
+Syntax:
+
+```bash
+picoclaw mcp add <name> [flags] <command-or-url> [args...]
+```
+
+Supported flags:
+
+| Flag | Meaning |
+|------|---------|
+| `--env`, `-e` | Add a stdio environment variable in `KEY=value` format. Repeatable. Values are saved to config. |
+| `--env-file` | Attach an env file path to a stdio server. Recommended for secrets you do not want stored inline in `config.json`. |
+| `--header`, `-H` | Add an HTTP header in `Name: Value` or `Name=Value` format. Repeatable. |
+| `--transport`, `-t` | Transport type: `stdio` (default), `http`, or `sse`. |
+| `--force`, `-f` | Overwrite an existing server entry without confirmation. |
+| `--deferred` | Mark the server as deferred: tools are hidden and discoverable on demand. |
+| `--no-deferred` | Mark the server as non-deferred: tools are always loaded into context. |
+
+When neither `--deferred` nor `--no-deferred` is passed, the `deferred` field is omitted from the stored config and the global `discovery.enabled` value applies at runtime.
+
+Supported forms:
+
+```bash
+picoclaw mcp add [flags] <name> <command-or-url> [args...]
+picoclaw mcp add [flags] <name> -- <command> [args...]
+```
+
+Parsing behavior:
+
+- CLI flags can appear before the name, between the name and target, or after the URL for remote transports
+- for `stdio`, the most robust form is `-- <command> [args...]`
+- use the `--` separator when the stdio command itself has arguments that may look like PicoClaw CLI flags
+- without `--`, PicoClaw treats the first two non-flag tokens as `<name>` and `<command-or-url>`
+
+Secret handling:
+
+- `--env KEY=value` stores the resolved value directly in `config.json`
+- use `--env-file` instead when the value is sensitive and should stay outside the main config file
+
+Example:
+
+```bash
+picoclaw mcp add sqlite npx -y @modelcontextprotocol/server-sqlite --db ./mydb.db
+```
+
+This stores:
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "sqlite": {
+          "enabled": true,
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db", "./mydb.db"]
+        }
+      }
+    }
+  }
+}
+```
+
+Adding the same server with `--deferred` stores the extra field:
+
+```bash
+picoclaw mcp add --deferred sqlite npx -y @modelcontextprotocol/server-sqlite --db ./mydb.db
+```
+
+```json
+{
+  "sqlite": {
+    "enabled": true,
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db", "./mydb.db"],
+    "deferred": true
+  }
+}
+```
+
+### Add Command Rules
+
+For `stdio`:
+
+- `<command-or-url>` is treated as the command
+- `[args...]` are stored in `args`
+- `--env` is supported
+- `--env-file` is supported and stored in `env_file`
+- `--header` is rejected
+- `-- <command> [args...]` is supported and recommended for unambiguous parsing
+
+For `http` / `sse`:
+
+- `<command-or-url>` must be a valid URL
+- extra command args are rejected
+- `--env` is rejected
+- `--env-file` is rejected
+- `--header` is supported and stored in `headers`
+
+Overwrite behavior:
+
+- if `<name>` already exists, PicoClaw asks for confirmation
+- use `--force` to skip the prompt
+
+Local path validation:
+
+- if the command looks like a local path such as `./server.py` or `/opt/mcp/server`
+- PicoClaw checks that the file exists
+- on non-Windows platforms, it also checks that the file is executable
+
+Clear URL/transport error:
+
+- if the target looks like `https://...` but transport is still `stdio`, PicoClaw returns an explicit error telling you to use `--transport http` or `--transport sse`
+
+## `picoclaw mcp remove`
+
+Syntax:
+
+```bash
+picoclaw mcp remove <name>
+```
+
+This removes the named entry from `tools.mcp.servers`.
+
+If the removed server was the last configured MCP server, PicoClaw also disables `tools.mcp.enabled`.
+
+## `picoclaw mcp list`
+
+Syntax:
+
+```bash
+picoclaw mcp list
+picoclaw mcp list --status
+```
+
+On wide terminals the output is a styled box (same look as `mcp show`). On narrow terminals or when stdout is not a TTY, a plain ASCII table is printed instead.
+
+Output fields:
+
+| Field | Meaning |
+|-------|---------|
+| `Name` | Server key inside `tools.mcp.servers` |
+| `Type` | Effective transport: `stdio`, `http`, or `sse` |
+| `Command` / `Target` | Stored command line for stdio servers, or URL for remote servers |
+| `Status` | `enabled` / `disabled` by default; with `--status`: `ok (N tools)` or `error` |
+| `Deferred` | `deferred` if the per-server override is `true`; `eager` if `false`; omitted if not set |
+
+Notes:
+
+- without `--status`, PicoClaw prints configuration state only
+- with `--status`, PicoClaw tries to connect to each enabled server and reports `ok (N tools)` or `error`
+- to see the full list of tools a server exposes, use `picoclaw mcp show <name>`
+
+## `picoclaw mcp show`
+
+Syntax:
+
+```bash
+picoclaw mcp show <name>
+picoclaw mcp show <name> --timeout 15s
+```
+
+This connects to the named server and prints:
+
+- server metadata: name, transport type, target, enabled state, deferred override, env var names, env file, header names
+- every tool the server exposes, with its name, description, and parameters (name, type, required/optional, description)
+
+On wide terminals the output is a styled box matching the `mcp list` look. On narrow terminals or non-TTY stdout, plain text is printed instead.
+
+Example output (wide terminal):
+
+```
+╭──────────────────────────────────────────────────────────╮
+│ ⬡  filesystem                                            │
+│                                                          │
+│ Type        stdio                                        │
+│ Target      npx -y @modelcontextprotocol/server-fs /tmp  │
+│ Enabled     yes                                          │
+│ Deferred    no                                           │
+│                                                          │
+│ Tools (3)                                                │
+│                                                          │
+│   read_file  [1/3]                                       │
+│   Read the complete contents of a file from the disk     │
+│                                                          │
+│     path  <string>  required                             │
+│       Path to the file to read                           │
+│ ──────────────────────────────────────────────────────── │
+│   ...                                                    │
+╰──────────────────────────────────────────────────────────╯
+```
+
+Flags:
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--timeout` | `10s` | Connection timeout |
+
+Notes:
+
+- if the server is disabled in config, `mcp show` prints the metadata only and skips tool discovery
+- `mcp show` always connects live to fetch the tool list; use `mcp test` if you only need a reachability check
+
+## `picoclaw mcp test`
+
+Syntax:
+
+```bash
+picoclaw mcp test <name>
+```
+
+This performs a direct connection test for one configured entry and prints the number of discovered tools when successful.
+
+It is useful when:
+
+- you want to verify a newly added server before starting the gateway
+- you want to debug one server without probing the whole list
+- the entry is currently disabled in config but you still want to validate its definition
+
+## `picoclaw mcp edit`
+
+Syntax:
+
+```bash
+picoclaw mcp edit
+```
+
+This opens the config file in the editor pointed to by `$EDITOR`.
+
+Use it when you need to configure MCP fields that are not exposed directly by `picoclaw mcp add`.
+
+If `$EDITOR` is not set, the command fails with an explicit error.
+
+## Recommended Workflow
+
+For common cases:
+
+1. Add the server with `picoclaw mcp add` (include `--deferred` if you want tools hidden by default).
+2. Verify connectivity and inspect the exposed tools with `picoclaw mcp show <name>`.
+3. Check all servers at a glance with `picoclaw mcp list --status`.
+4. Start PicoClaw normally so the configured MCP server is loaded by the host.
+
+For advanced cases:
+
+1. Add the base entry with `picoclaw mcp add`.
+2. Run `picoclaw mcp edit` to fill in fields that are not exposed as CLI flags.
+3. Run `picoclaw mcp show <name>` to confirm the final configuration and tool list.
+
+## Related Docs
+
+- [Tools Configuration](tools_configuration.md#mcp-tool): MCP config structure, transports, discovery, and examples
+- [README](../README.md): high-level overview

docs/reference/tools_configuration.md

@@ -258,6 +258,17 @@ For schedule types, execution modes (`deliver`, agent turn, and command jobs), p
 
 The MCP tool enables integration with external Model Context Protocol servers.
 
+If you prefer not to edit JSON manually, PicoClaw also provides an MCP configuration manager CLI:
+
+- `picoclaw mcp add` — add or update a server (supports `--deferred` / `--no-deferred`)
+- `picoclaw mcp list` — list all configured servers with status and deferred state
+- `picoclaw mcp show <name>` — show full details and the tool list for one server
+- `picoclaw mcp test <name>` — connectivity check for one server
+- `picoclaw mcp remove <name>` — remove a server entry
+- `picoclaw mcp edit` — open `config.json` in `$EDITOR` for advanced edits
+
+These commands manage the same `tools.mcp.servers` section documented below. See [MCP Server CLI](mcp-cli.md) for command syntax, examples, and behavior details.
+
 ### Tool Discovery (Lazy Loading)
 
 When connecting to multiple MCP servers, exposing hundreds of tools simultaneously can exhaust the LLM's context window

go.mod

@@ -4,26 +4,24 @@ go 1.25.9
 
 require (
 	fyne.io/systray v1.12.0
-	github.com/BurntSushi/toml v1.6.0
 	github.com/SevereCloud/vksdk/v3 v3.3.1
 	github.com/adhocore/gronx v1.19.6
 	github.com/anthropics/anthropic-sdk-go v1.26.0
 	github.com/atc0005/go-teams-notify/v2 v2.14.0
-	github.com/aws/aws-sdk-go-v2 v1.41.5
-	github.com/aws/aws-sdk-go-v2/config v1.32.14
-	github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.4
+	github.com/aws/aws-sdk-go-v2 v1.41.6
+	github.com/aws/aws-sdk-go-v2/config v1.32.16
+	github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.5
 	github.com/bwmarrin/discordgo v0.29.0
 	github.com/caarlos0/env/v11 v11.4.0
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/creack/pty v1.1.24
 	github.com/ergochat/irc-go v0.6.0
 	github.com/ergochat/readline v0.1.3
-	github.com/gdamore/tcell/v2 v2.13.8
 	github.com/gomarkdown/markdown v0.0.0-20260411013819-759bbc3e3207
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/h2non/filetype v1.1.3
-	github.com/larksuite/oapi-sdk-go/v3 v3.5.3
+	github.com/larksuite/oapi-sdk-go/v3 v3.5.4
 	github.com/mdp/qrterminal/v3 v3.2.1
 	github.com/minio/selfupdate v0.6.0
 	github.com/modelcontextprotocol/go-sdk v1.5.0
@@ -33,8 +31,7 @@ require (
 	github.com/openai/openai-go/v3 v3.22.0
 	github.com/pion/rtp v1.10.1
 	github.com/pion/webrtc/v3 v3.3.6
-	github.com/rivo/tview v0.42.0
-	github.com/rs/zerolog v1.35.0
+	github.com/rs/zerolog v1.35.1
 	github.com/slack-go/slack v0.17.3
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.10
@@ -55,19 +52,19 @@ require (
 require (
 	aead.dev/minisign v0.2.0 // indirect
 	filippo.io/edwards25519 v1.2.0 // indirect
-	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.14 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.0.9 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.15 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.41.10 // indirect
-	github.com/aws/smithy-go v1.24.2 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.15 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.0.10 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.16 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.42.0 // indirect
+	github.com/aws/smithy-go v1.25.0 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/beeper/argo-go v1.1.2 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
@@ -79,7 +76,6 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/elliotchance/orderedmap/v3 v3.1.0 // indirect
-	github.com/gdamore/encoding v1.0.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
@@ -122,7 +118,7 @@ require (
 	github.com/github/copilot-sdk/go v0.2.0
 	github.com/go-resty/resty/v2 v2.17.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/google/jsonschema-go v0.4.2 // indirect
+	github.com/google/jsonschema-go v0.4.2
 	github.com/grbit/go-json v0.11.0 // indirect
 	github.com/klauspost/compress v1.18.4 // indirect
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect

go.sum

@@ -5,8 +5,6 @@ filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
 filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 fyne.io/systray v1.12.0 h1:CA1Kk0e2zwFlxtc02L3QFSiIbxJ/P0n582YrZHT7aTM=
 fyne.io/systray v1.12.0/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
-github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
-github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
 github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
 github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
 github.com/SevereCloud/vksdk/v3 v3.3.1 h1:O86zsp5LQnHE+O5acvuXM/s6S1LyxzVTkF6+Lup0Jyg=
@@ -23,38 +21,38 @@ github.com/anthropics/anthropic-sdk-go v1.26.0 h1:oUTzFaUpAevfuELAP1sjL6CQJ9HHAf
 github.com/anthropics/anthropic-sdk-go v1.26.0/go.mod h1:qUKmaW+uuPB64iy1l+4kOSvaLqPXnHTTBKH6RVZ7q5Q=
 github.com/atc0005/go-teams-notify/v2 v2.14.0 h1:7N+xw+COnYANLREaAveQ65rsNQ12nIZJED9nMLyscCo=
 github.com/atc0005/go-teams-notify/v2 v2.14.0/go.mod h1:EECsWM2b0Hvoz7O+QdlsvyN2KCUOFQCGj8bUBXv3A3Q=
-github.com/aws/aws-sdk-go-v2 v1.41.5 h1:dj5kopbwUsVUVFgO4Fi5BIT3t4WyqIDjGKCangnV/yY=
-github.com/aws/aws-sdk-go-v2 v1.41.5/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 h1:eBMB84YGghSocM7PsjmmPffTa+1FBUeNvGvFou6V/4o=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
-github.com/aws/aws-sdk-go-v2/config v1.32.14 h1:opVIRo/ZbbI8OIqSOKmpFaY7IwfFUOCCXBsUpJOwDdI=
-github.com/aws/aws-sdk-go-v2/config v1.32.14/go.mod h1:U4/V0uKxh0Tl5sxmCBZ3AecYny4UNlVmObYjKuuaiOo=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.14 h1:n+UcGWAIZHkXzYt87uMFBv/l8THYELoX6gVcUvgl6fI=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.14/go.mod h1:cJKuyWB59Mqi0jM3nFYQRmnHVQIcgoxjEMAbLkpr62w=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21 h1:NUS3K4BTDArQqNu2ih7yeDLaS3bmHD0YndtA6UP884g=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.21/go.mod h1:YWNWJQNjKigKY1RHVJCuupeWDrrHjRqHm0N9rdrWzYI=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21 h1:Rgg6wvjjtX8bNHcvi9OnXWwcE0a2vGpbwmtICOsvcf4=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.21/go.mod h1:A/kJFst/nm//cyqonihbdpQZwiUhhzpqTsdbhDdRF9c=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21 h1:PEgGVtPoB6NTpPrBgqSE5hE/o47Ij9qk/SEZFbUOe9A=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.21/go.mod h1:p+hz+PRAYlY3zcpJhPwXlLC4C+kqn70WIHwnzAfs6ps=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 h1:qYQ4pzQ2Oz6WpQ8T3HvGHnZydA72MnLuFK9tJwmrbHw=
-github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6/go.mod h1:O3h0IK87yXci+kg6flUKzJnWeziQUKciKrLjcatSNcY=
-github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.4 h1:W6tKfa/s37faUnwJ71pGqsBO7/wfUX1L7tVprupQGo4=
-github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.4/go.mod h1:BZ+9thH0QOTDUwE8KAv/ZwUzsNC7CSMJXj/wtnZMs5k=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21 h1:c31//R3xgIJMSC8S6hEVq+38DcvUlgFY0FM6mSI5oto=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.21/go.mod h1:r6+pf23ouCB718FUxaqzZdbpYFyDtehyZcmP5KL9FkA=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.9 h1:QKZH0S178gCmFEgst8hN0mCX1KxLgHBKKY/CLqwP8lg=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.9/go.mod h1:7yuQJoT+OoH8aqIxw9vwF+8KpvLZ8AWmvmUWHsGQZvI=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.15 h1:lFd1+ZSEYJZYvv9d6kXzhkZu07si3f+GQ1AaYwa2LUM=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.15/go.mod h1:WSvS1NLr7JaPunCXqpJnWk1Bjo7IxzZXrZi1QQCkuqM=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19 h1:dzztQ1YmfPrxdrOiuZRMF6fuOwWlWpD2StNLTceKpys=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.19/go.mod h1:YO8TrYtFdl5w/4vmjL8zaBSsiNp3w0L1FfKVKenZT7w=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.10 h1:p8ogvvLugcR/zLBXTXrTkj0RYBUdErbMnAFFp12Lm/U=
-github.com/aws/aws-sdk-go-v2/service/sts v1.41.10/go.mod h1:60dv0eZJfeVXfbT1tFJinbHrDfSJ2GZl4Q//OSSNAVw=
-github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
-github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/aws/aws-sdk-go-v2 v1.41.6 h1:1AX0AthnBQzMx1vbmir3Y4WsnJgiydmnJjiLu+LvXOg=
+github.com/aws/aws-sdk-go-v2 v1.41.6/go.mod h1:dy0UzBIfwSeot4grGvY1AqFWN5zgziMmWGzysDnHFcQ=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9 h1:adBsCIIpLbLmYnkQU+nAChU5yhVTvu5PerROm+/Kq2A=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9/go.mod h1:uOYhgfgThm/ZyAuJGNQ5YgNyOlYfqnGpTHXvk3cpykg=
+github.com/aws/aws-sdk-go-v2/config v1.32.16 h1:Q0iQ7quUgJP0F/SCRTieScnaMdXr9h/2+wze1u3cNeM=
+github.com/aws/aws-sdk-go-v2/config v1.32.16/go.mod h1:duCCnJEFqpt2RC6no1iK6q+8HpwOAkiUua0pY507dQc=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.15 h1:fyvgWTszojq8hEnMi8PPBTvZdTtEVmAVyo+NFLHBhH4=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.15/go.mod h1:gJiYyMOjNg8OEdRWOf3CrFQxM2a98qmrtjx1zuiQfB8=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22 h1:IOGsJ1xVWhsi+ZO7/NW8OuZZBtMJLZbk4P5HDjJO0jQ=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22/go.mod h1:b+hYdbU+jGKfXE8kKM6g1+h+L/Go3vMvzlxBsiuGsxg=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22 h1:GmLa5Kw1ESqtFpXsx5MmC84QWa/ZrLZvlJGa2y+4kcQ=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22/go.mod h1:6sW9iWm9DK9YRpRGga/qzrzNLgKpT2cIxb7Vo2eNOp0=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22 h1:dY4kWZiSaXIzxnKlj17nHnBcXXBfac6UlsAx2qL6XrU=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22/go.mod h1:KIpEUx0JuRZLO7U6cbV204cWAEco2iC3l061IxlwLtI=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23 h1:FPXsW9+gMuIeKmz7j6ENWcWtBGTe1kH8r9thNt5Uxx4=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23/go.mod h1:7J8iGMdRKk6lw2C+cMIphgAnT8uTwBwNOsGkyOCm80U=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.5 h1:ZGTl4Rxft1uyENAlGESY04hMzE4cLLNUPI7dGw08haw=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.5/go.mod h1:jnugA+VgESQGgXuEKK6zVToET/DtODq7LQYpe+BkKT4=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8 h1:HtOTYcbVcGABLOVuPYaIihj6IlkqubBwFj10K5fxRek=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8/go.mod h1:VsK9abqQeGlzPgUr+isNWzPlK2vKe9INMLWnY65f5Xs=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22 h1:PUmZeJU6Y1Lbvt9WFuJ0ugUK2xn6hIWUBBbKuOWF30s=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22/go.mod h1:nO6egFBoAaoXze24a2C0NjQCvdpk8OueRoYimvEB9jo=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.10 h1:a1Fq/KXn75wSzoJaPQTgZO0wHGqE9mjFnylnqEPTchA=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.10/go.mod h1:p6+MXNxW7IA6dMgHfTAzljuwSKD0NCm/4lbS4t6+7vI=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.16 h1:x6bKbmDhsgSZwv6q19wY/u3rLk/3FGjJWyqKcIRufpE=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.16/go.mod h1:CudnEVKRtLn0+3uMV0yEXZ+YZOKnAtUJ5DmDhilVnIw=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20 h1:oK/njaL8GtyEihkWMD4k3VgHCT64RQKkZwh0DG5j8ak=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20/go.mod h1:JHs8/y1f3zY7U5WcuzoJ/yAYGYtNIVPKLIbp61euvmg=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.0 h1:ks8KBcZPh3PYISr5dAiXCM5/Thcuxk8l+PG4+A0exds=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.0/go.mod h1:pFw33T0WLvXU3rw1WBkpMlkgIn54eCB5FYLhjDc9Foo=
+github.com/aws/smithy-go v1.25.0 h1:Sz/XJ64rwuiKtB6j98nDIPyYrV1nVNJ4YU74gttcl5U=
+github.com/aws/smithy-go v1.25.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/beeper/argo-go v1.1.2 h1:UQI2G8F+NLfGTOmTUI0254pGKx/HUU/etbUGTJv91Fs=
@@ -105,10 +103,6 @@ github.com/ergochat/readline v0.1.3 h1:/DytGTmwdUJcLAe3k3VJgowh5vNnsdifYT6uVaf4p
 github.com/ergochat/readline v0.1.3/go.mod h1:o3ux9QLHLm77bq7hDB21UTm6HlV2++IPDMfIfKDuOgY=
 github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
 github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
-github.com/gdamore/encoding v1.0.1 h1:YzKZckdBL6jVt2Gc+5p82qhrGiqMdG/eNs6Wy0u3Uhw=
-github.com/gdamore/encoding v1.0.1/go.mod h1:0Z0cMFinngz9kS1QfMjCP8TY7em3bZYeeklsSDPivEo=
-github.com/gdamore/tcell/v2 v2.13.8 h1:Mys/Kl5wfC/GcC5Cx4C2BIQH9dbnhnkPgS9/wF3RlfU=
-github.com/gdamore/tcell/v2 v2.13.8/go.mod h1:+Wfe208WDdB7INEtCsNrAN6O2m+wsTPk1RAovjaILlo=
 github.com/github/copilot-sdk/go v0.2.0 h1:RnrIIirmtp4wGgqSQFJ2k9phbeveIxOtYZqDogoNEa0=
 github.com/github/copilot-sdk/go v0.2.0/go.mod h1:uGWkjVYcp2DV9DgtqYihh5tEoJjNqxIFaUNnrwY4FxM=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -138,8 +132,6 @@ github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvq
 github.com/golang/protobuf v1.4.2/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI=
 github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
 github.com/golang/protobuf v1.5.2/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
-github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab h1:VYNivV7P8IRHUam2swVUNkhIdp0LRRFKe4hXNnoZKTc=
-github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/gomarkdown/markdown v0.0.0-20260411013819-759bbc3e3207 h1:p7t34F7K4OCRQblcDhNJnP46Uaarz3z2cLcvOZYxWn8=
 github.com/gomarkdown/markdown v0.0.0-20260411013819-759bbc3e3207/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
@@ -185,8 +177,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.3 h1:xvf8Dv29kBXC5/DNDCLhHkAFW8l/0LlQJimO5Zn+JUk=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.3/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.4 h1:U2S9x9LrfH++ZqJ+YAiUlqzCWJmVXhFdS8Z7rIBH8H0=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.4/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
 github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
 github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
@@ -234,8 +226,6 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
-github.com/rivo/tview v0.42.0 h1:b/ftp+RxtDsHSaynXTbJb+/n/BxDEi+W3UfF5jILK6c=
-github.com/rivo/tview v0.42.0/go.mod h1:cSfIYfhpSGCjp3r/ECJb+GKS7cGJnqV8vfjQPwoXyfY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
@@ -243,8 +233,8 @@ github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTE
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/rogpeppe/go-internal v1.13.1 h1:KvO1DLK/DRN07sQ1LQKScxyZJuNnedQ5/wKSR38lUII=
 github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWNMNyH2VO9fmH0o=
-github.com/rs/zerolog v1.35.0 h1:VD0ykx7HMiMJytqINBsKcbLS+BJ4WYjz+05us+LRTdI=
-github.com/rs/zerolog v1.35.0/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
+github.com/rs/zerolog v1.35.1 h1:m7xQeoiLIiV0BCEY4Hs+j2NG4Gp2o2KPKmhnnLiazKI=
+github.com/rs/zerolog v1.35.1/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
 github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=

pkg/agent/adapters/channelmanager.go

@@ -43,3 +43,9 @@ func (a *channelManagerAdapter) SendMedia(ctx context.Context, msg bus.OutboundM
 func (a *channelManagerAdapter) SendPlaceholder(ctx context.Context, channel, chatID string) bool {
 	return a.inner.SendPlaceholder(ctx, channel, chatID)
 }
+
+func (a *channelManagerAdapter) DismissToolFeedback(
+	ctx context.Context, channel, chatID string, outboundCtx *bus.InboundContext,
+) {
+	a.inner.DismissToolFeedback(ctx, channel, chatID, outboundCtx)
+}

pkg/agent/agent.go

@@ -111,8 +111,10 @@ const (
 	sessionKeyAgentPrefix      = "agent:"
 	pendingTurnPrefix          = "pending-"
 	metadataKeyMessageKind     = "message_kind"
+	metadataKeyToolCalls       = "tool_calls"
 	messageKindThought         = "thought"
 	messageKindToolFeedback    = "tool_feedback"
+	messageKindToolCalls       = "tool_calls"
 	metadataKeyAccountID       = "account_id"
 	metadataKeyGuildID         = "guild_id"
 	metadataKeyTeamID          = "team_id"

pkg/agent/agent_init.go

@@ -128,6 +128,9 @@ func registerSharedTools(
 		if cfg.Tools.IsToolEnabled("spi") {
 			agent.Tools.Register(tools.NewSPITool())
 		}
+		if cfg.Tools.IsToolEnabled("serial") {
+			agent.Tools.Register(tools.NewSerialTool())
+		}
 
 		// Message tool
 		if cfg.Tools.IsToolEnabled("message") {

pkg/agent/agent_mcp.go

@@ -135,6 +135,25 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
 			serverCfg := al.cfg.Tools.MCP.Servers[serverName]
 			registerAsHidden := serverIsDeferred(al.cfg.Tools.MCP.Discovery.Enabled, serverCfg)
 
+			for _, agentID := range agentIDs {
+				agent, ok := al.registry.GetAgent(agentID)
+				if !ok || agent.ContextBuilder == nil {
+					continue
+				}
+				if err := agent.ContextBuilder.RegisterPromptContributor(mcpServerPromptContributor{
+					serverName: serverName,
+					toolCount:  len(conn.Tools),
+					deferred:   registerAsHidden,
+				}); err != nil {
+					logger.WarnCF("agent", "Failed to register MCP prompt contributor",
+						map[string]any{
+							"agent_id": agentID,
+							"server":   serverName,
+							"error":    err.Error(),
+						})
+				}
+			}
+
 			for _, tool := range conn.Tools {
 				for _, agentID := range agentIDs {
 					agent, ok := al.registry.GetAgent(agentID)

pkg/agent/agent_media.go

@@ -11,6 +11,7 @@ import (
 	"encoding/base64"
 	"io"
 	"os"
+	"regexp"
 	"strings"
 
 	"github.com/h2non/filetype"
@@ -20,24 +21,59 @@ import (
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
+// genericPlaceholderRegex matches generic media placeholders emitted by various
+// channels: [image], [image: photo], [image: filename.jpg] — but NOT path tags
+// like [image:/path/to/file] (path tags have no space after the colon).
+var (
+	imagePlaceholderRegex = regexp.MustCompile(`\[image(:\s+[^\]]*)?\]`)
+	audioPlaceholderRegex = regexp.MustCompile(`\[audio(:\s+[^\]]*)?\]`)
+	videoPlaceholderRegex = regexp.MustCompile(`\[video(:\s+[^\]]*)?\]`)
+	filePlaceholderRegex  = regexp.MustCompile(`\[file(:\s+[^\]]*)?\]`)
+)
+
 // resolveMediaRefs resolves media:// refs in messages.
-// Images are base64-encoded into the Media array for multimodal LLMs.
-// Non-image files (documents, audio, video) have their local path injected
-// into Content so the agent can access them via file tools like read_file.
+// For user messages: images get path tags only ([image:/path]) so the LLM
+// can decide whether to view them via load_image or operate on the file.
+// For tool messages: images are base64-encoded and appended as a synthetic
+// user message only after the contiguous tool-message block ends, so we don't
+// break the tool-results-must-immediately-follow-assistant constraint that
+// LLM APIs enforce.
+// Non-image files always get path tags regardless of role.
 // Returns a new slice; original messages are not mutated.
 func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxSize int) []providers.Message {
 	if store == nil {
 		return messages
 	}
 
-	result := make([]providers.Message, len(messages))
-	copy(result, messages)
+	result := make([]providers.Message, 0, len(messages))
+	var pendingToolImages []string
+
+	for idx, m := range messages {
+		// When leaving a tool-message block, flush any accumulated images
+		// as a synthetic user message.
+		if m.Role != "tool" && len(pendingToolImages) > 0 {
+			result = append(result, providers.Message{
+				Role:    "user",
+				Content: "[Loaded image from tool result above]",
+				Media:   pendingToolImages,
+			})
+			pendingToolImages = nil
+		}
 
-	for i, m := range result {
 		if len(m.Media) == 0 {
+			result = append(result, m)
+			if idx == len(messages)-1 && len(pendingToolImages) > 0 {
+				result = append(result, providers.Message{
+					Role:    "user",
+					Content: "[Loaded image from tool result above]",
+					Media:   pendingToolImages,
+				})
+				pendingToolImages = nil
+			}
 			continue
 		}
 
+		msg := m
 		resolved := make([]string, 0, len(m.Media))
 		var pathTags []string
 
@@ -66,13 +102,13 @@ func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxS
 			}
 
 			mime := detectMIME(localPath, meta)
+			pathTags = append(pathTags, buildPathTag(mime, localPath))
 
-			if strings.HasPrefix(mime, "image/") {
+			if m.Role == "tool" && strings.HasPrefix(mime, "image/") {
 				dataURL := encodeImageToDataURL(localPath, mime, info, maxSize)
 				if dataURL != "" {
-					resolved = append(resolved, dataURL)
+					pendingToolImages = append(pendingToolImages, dataURL)
 				}
-				continue
 			}
 
 			if strings.HasPrefix(mime, "audio/") {
@@ -83,18 +119,69 @@ func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxS
 				continue
 			}
 
-			pathTags = append(pathTags, buildPathTag(mime, localPath))
 		}
 
-		result[i].Media = resolved
+		msg.Media = resolved
 		if len(pathTags) > 0 {
-			result[i].Content = injectPathTags(result[i].Content, pathTags)
+			msg.Content = injectPathTags(msg.Content, pathTags)
+		}
+		result = append(result, msg)
+
+		// If this is the last message and we have pending images, flush them.
+		if idx == len(messages)-1 && len(pendingToolImages) > 0 {
+			result = append(result, providers.Message{
+				Role:    "user",
+				Content: "[Loaded image from tool result above]",
+				Media:   pendingToolImages,
+			})
+			pendingToolImages = nil
 		}
 	}
 
 	return result
 }
 
+// encodeImageToDataURL base64-encodes an image file into a data URL.
+// Returns empty string if the file exceeds maxSize or encoding fails.
+func encodeImageToDataURL(localPath, mime string, info os.FileInfo, maxSize int) string {
+	if info.Size() > int64(maxSize) {
+		logger.WarnCF("agent", "Media file too large, skipping", map[string]any{
+			"path":     localPath,
+			"size":     info.Size(),
+			"max_size": maxSize,
+		})
+		return ""
+	}
+
+	f, err := os.Open(localPath)
+	if err != nil {
+		logger.WarnCF("agent", "Failed to open media file", map[string]any{
+			"path":  localPath,
+			"error": err.Error(),
+		})
+		return ""
+	}
+	defer f.Close()
+
+	prefix := "data:" + mime + ";base64,"
+	encodedLen := base64.StdEncoding.EncodedLen(int(info.Size()))
+	var buf bytes.Buffer
+	buf.Grow(len(prefix) + encodedLen)
+	buf.WriteString(prefix)
+
+	encoder := base64.NewEncoder(base64.StdEncoding, &buf)
+	if _, err := io.Copy(encoder, f); err != nil {
+		logger.WarnCF("agent", "Failed to encode media file", map[string]any{
+			"path":  localPath,
+			"error": err.Error(),
+		})
+		return ""
+	}
+	encoder.Close()
+
+	return buf.String()
+}
+
 func buildArtifactTags(store media.MediaStore, refs []string) []string {
 	if store == nil || len(refs) == 0 {
 		return nil
@@ -145,51 +232,12 @@ func detectMIME(localPath string, meta media.MediaMeta) string {
 	return kind.MIME.Value
 }
 
-// encodeImageToDataURL base64-encodes an image file into a data URL.
-// Returns empty string if the file exceeds maxSize or encoding fails.
-func encodeImageToDataURL(localPath, mime string, info os.FileInfo, maxSize int) string {
-	if info.Size() > int64(maxSize) {
-		logger.WarnCF("agent", "Media file too large, skipping", map[string]any{
-			"path":     localPath,
-			"size":     info.Size(),
-			"max_size": maxSize,
-		})
-		return ""
-	}
-
-	f, err := os.Open(localPath)
-	if err != nil {
-		logger.WarnCF("agent", "Failed to open media file", map[string]any{
-			"path":  localPath,
-			"error": err.Error(),
-		})
-		return ""
-	}
-	defer f.Close()
-
-	prefix := "data:" + mime + ";base64,"
-	encodedLen := base64.StdEncoding.EncodedLen(int(info.Size()))
-	var buf bytes.Buffer
-	buf.Grow(len(prefix) + encodedLen)
-	buf.WriteString(prefix)
-
-	encoder := base64.NewEncoder(base64.StdEncoding, &buf)
-	if _, err := io.Copy(encoder, f); err != nil {
-		logger.WarnCF("agent", "Failed to encode media file", map[string]any{
-			"path":  localPath,
-			"error": err.Error(),
-		})
-		return ""
-	}
-	encoder.Close()
-
-	return buf.String()
-}
-
 // buildPathTag creates a structured tag exposing the local file path.
-// Tag type is derived from MIME: [audio:/path], [video:/path], or [file:/path].
+// Tag type is derived from MIME: [image:/path], [audio:/path], [video:/path], or [file:/path].
 func buildPathTag(mime, localPath string) string {
 	switch {
+	case strings.HasPrefix(mime, "image/"):
+		return "[image:" + localPath + "]"
 	case strings.HasPrefix(mime, "audio/"):
 		return "[audio:" + localPath + "]"
 	case strings.HasPrefix(mime, "video/"):
@@ -200,22 +248,41 @@ func buildPathTag(mime, localPath string) string {
 }
 
 // injectPathTags replaces generic media tags in content with path-bearing versions,
-// or appends if no matching generic tag is found.
+// or appends if no matching generic tag is found. Channels emit a few different
+// placeholder formats — [image], [image: photo], [image: filename.jpg] — so we
+// match all of them via regex while leaving path tags ([image:/path]) untouched.
+//
+// When content is structured data (e.g., JSON from Feishu interactive cards or
+// post messages), tags are only injected via placeholder replacement — never
+// appended — to avoid corrupting the payload.
 func injectPathTags(content string, tags []string) string {
+	isStructured := looksLikeJSON(content)
 	for _, tag := range tags {
-		var generic string
+		var pattern *regexp.Regexp
 		switch {
+		case strings.HasPrefix(tag, "[image:"):
+			pattern = imagePlaceholderRegex
 		case strings.HasPrefix(tag, "[audio:"):
-			generic = "[audio]"
+			pattern = audioPlaceholderRegex
 		case strings.HasPrefix(tag, "[video:"):
-			generic = "[video]"
+			pattern = videoPlaceholderRegex
 		case strings.HasPrefix(tag, "[file:"):
-			generic = "[file]"
+			pattern = filePlaceholderRegex
 		}
 
-		if generic != "" && strings.Contains(content, generic) {
-			content = strings.Replace(content, generic, tag, 1)
-		} else if content == "" {
+		if pattern != nil {
+			if loc := pattern.FindStringIndex(content); loc != nil {
+				content = content[:loc[0]] + tag + content[loc[1]:]
+				continue
+			}
+		}
+
+		if isStructured {
+			content = tag + "\n" + content
+			continue
+		}
+
+		if content == "" {
 			content = tag
 		} else {
 			content += " " + tag
@@ -223,3 +290,8 @@ func injectPathTags(content string, tags []string) string {
 	}
 	return content
 }
+
+func looksLikeJSON(s string) bool {
+	s = strings.TrimSpace(s)
+	return len(s) > 1 && s[0] == '{'
+}

pkg/agent/agent_outbound.go

@@ -4,13 +4,17 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/tools"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 func (al *AgentLoop) maybePublishError(ctx context.Context, channel, chatID, sessionKey string, err error) bool {
@@ -123,6 +127,95 @@ func (al *AgentLoop) publishPicoReasoning(ctx context.Context, reasoningContent,
 	}
 }
 
+func (al *AgentLoop) publishPicoToolCallInterim(
+	ctx context.Context,
+	ts *turnState,
+	reasoningContent string,
+	content string,
+	toolCalls []providers.ToolCall,
+) {
+	if ts == nil || ts.chatID == "" || al == nil || al.bus == nil {
+		return
+	}
+
+	if strings.TrimSpace(reasoningContent) != "" {
+		pubCtx, pubCancel := context.WithTimeout(ctx, 3*time.Second)
+		err := al.bus.PublishOutbound(
+			pubCtx,
+			outboundMessageForTurnWithKind(ts, reasoningContent, messageKindThought),
+		)
+		pubCancel()
+		if err != nil && !errors.Is(err, context.DeadlineExceeded) &&
+			!errors.Is(err, context.Canceled) &&
+			!errors.Is(err, bus.ErrBusClosed) {
+			logger.WarnCF("agent", "Failed to publish pico reasoning", map[string]any{
+				"channel": ts.channel,
+				"chat_id": ts.chatID,
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	if !ts.opts.AllowInterimPicoPublish {
+		return
+	}
+
+	visibleToolCalls := utils.BuildVisibleToolCalls(
+		toolCalls,
+		al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
+	)
+	duplicateToolCallContent := len(visibleToolCalls) > 0 &&
+		utils.ToolCallExplanationDuplicatesContent(content, toolCalls)
+
+	if strings.TrimSpace(content) != "" && !duplicateToolCallContent {
+		pubCtx, pubCancel := context.WithTimeout(ctx, 3*time.Second)
+		err := al.bus.PublishOutbound(pubCtx, outboundMessageForTurn(ts, content))
+		pubCancel()
+		if err != nil && !errors.Is(err, context.DeadlineExceeded) &&
+			!errors.Is(err, context.Canceled) &&
+			!errors.Is(err, bus.ErrBusClosed) {
+			logger.WarnCF("agent", "Failed to publish pico interim assistant content", map[string]any{
+				"channel": ts.channel,
+				"chat_id": ts.chatID,
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	if len(visibleToolCalls) == 0 {
+		return
+	}
+
+	rawToolCalls, err := json.Marshal(visibleToolCalls)
+	if err != nil {
+		logger.WarnCF("agent", "Failed to serialize pico tool calls", map[string]any{
+			"channel": ts.channel,
+			"chat_id": ts.chatID,
+			"error":   err.Error(),
+		})
+		return
+	}
+
+	msg := outboundMessageForTurnWithKind(ts, "", messageKindToolCalls)
+	if msg.Context.Raw == nil {
+		msg.Context.Raw = map[string]string{}
+	}
+	msg.Context.Raw[metadataKeyToolCalls] = string(rawToolCalls)
+
+	pubCtx, pubCancel := context.WithTimeout(ctx, 3*time.Second)
+	err = al.bus.PublishOutbound(pubCtx, msg)
+	pubCancel()
+	if err != nil && !errors.Is(err, context.DeadlineExceeded) &&
+		!errors.Is(err, context.Canceled) &&
+		!errors.Is(err, bus.ErrBusClosed) {
+		logger.WarnCF("agent", "Failed to publish pico tool calls", map[string]any{
+			"channel": ts.channel,
+			"chat_id": ts.chatID,
+			"error":   err.Error(),
+		})
+	}
+}
+
 func (al *AgentLoop) handleReasoning(
 	ctx context.Context,
 	reasoningContent, channelName, channelID string,

pkg/agent/agent_test.go

@@ -1720,6 +1720,38 @@ func (m *messageToolProvider) GetDefaultModel() string {
 	return "message-tool-model"
 }
 
+type reasoningVisibleToolProvider struct {
+	filePath string
+	calls    int
+}
+
+func (m *reasoningVisibleToolProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	if m.calls == 1 {
+		return &providers.LLMResponse{
+			Content:          "I'll inspect that file now.",
+			ReasoningContent: "Read the file before answering.",
+			ToolCalls: []providers.ToolCall{{
+				ID:        "call_read_file",
+				Type:      "function",
+				Name:      "read_file",
+				Arguments: map[string]any{"path": m.filePath},
+			}},
+		}, nil
+	}
+	return &providers.LLMResponse{Content: "DONE"}, nil
+}
+
+func (m *reasoningVisibleToolProvider) GetDefaultModel() string {
+	return "reasoning-visible-tool-model"
+}
+
 type artifactThenSendProvider struct {
 	calls int
 }
@@ -1749,17 +1781,22 @@ func (m *artifactThenSendProvider) Chat(
 		if messages[i].Role != "tool" {
 			continue
 		}
-		start := strings.Index(messages[i].Content, "[file:")
-		if start < 0 {
-			continue
+		for _, prefix := range []string{"[image:", "[file:", "[audio:", "[video:"} {
+			start := strings.Index(messages[i].Content, prefix)
+			if start < 0 {
+				continue
+			}
+			rest := messages[i].Content[start+len(prefix):]
+			end := strings.Index(rest, "]")
+			if end < 0 {
+				continue
+			}
+			artifactPath = rest[:end]
+			break
 		}
-		rest := messages[i].Content[start+len("[file:"):]
-		end := strings.Index(rest, "]")
-		if end < 0 {
-			continue
+		if artifactPath != "" {
+			break
 		}
-		artifactPath = rest[:end]
-		break
 	}
 	if artifactPath == "" {
 		return nil, fmt.Errorf("provider did not receive artifact path in tool result")
@@ -1860,12 +1897,34 @@ func TestToolFeedbackExplanationFromResponse_UsesCurrentContentFirst(t *testing.
 		{Role: "tool", Content: "tool output", ToolCallID: "call_1"},
 	}
 
-	got := toolFeedbackExplanationFromResponse(response, messages, 300)
+	got := toolFeedbackExplanationFromResponse(response, messages)
 	if got != "Read README.md first" {
 		t.Fatalf("toolFeedbackExplanationFromResponse() = %q, want current content", got)
 	}
 }
 
+func TestSideQuestionResponseContent_FallsBackWhenContentIsWhitespace(t *testing.T) {
+	response := &providers.LLMResponse{
+		Content:          " \n\t ",
+		ReasoningContent: "reasoning fallback",
+	}
+
+	if got := sideQuestionResponseContent(response); got != "reasoning fallback" {
+		t.Fatalf("sideQuestionResponseContent() = %q, want %q", got, "reasoning fallback")
+	}
+}
+
+func TestResponseReasoningContent_FallsBackWhenReasoningIsWhitespace(t *testing.T) {
+	response := &providers.LLMResponse{
+		Reasoning:        " \n\t ",
+		ReasoningContent: "structured reasoning fallback",
+	}
+
+	if got := responseReasoningContent(response); got != "structured reasoning fallback" {
+		t.Fatalf("responseReasoningContent() = %q, want %q", got, "structured reasoning fallback")
+	}
+}
+
 func TestToolFeedbackExplanationFromResponse_UsesExplicitToolCallExtraContent(t *testing.T) {
 	response := &providers.LLMResponse{
 		ToolCalls: []providers.ToolCall{{
@@ -1882,7 +1941,7 @@ func TestToolFeedbackExplanationFromResponse_UsesExplicitToolCallExtraContent(t
 		{Role: "tool", Content: "tool output", ToolCallID: "call_1"},
 	}
 
-	got := toolFeedbackExplanationFromResponse(response, messages, 300)
+	got := toolFeedbackExplanationFromResponse(response, messages)
 	if got != "Read README.md first to confirm the current project structure." {
 		t.Fatalf("toolFeedbackExplanationFromResponse() = %q, want explicit tool feedback explanation", got)
 	}
@@ -1909,8 +1968,8 @@ func TestToolFeedbackExplanationForToolCall_PrefersToolSpecificExtraContent(t *t
 		},
 	}
 
-	got1 := toolFeedbackExplanationForToolCall(response, response.ToolCalls[0], nil, 300)
-	got2 := toolFeedbackExplanationForToolCall(response, response.ToolCalls[1], nil, 300)
+	got1 := toolFeedbackExplanationForToolCall(response, response.ToolCalls[0], nil)
+	got2 := toolFeedbackExplanationForToolCall(response, response.ToolCalls[1], nil)
 	if got1 != "Read README.md first." {
 		t.Fatalf("toolFeedbackExplanationForToolCall() first = %q, want tool-specific explanation", got1)
 	}
@@ -1939,7 +1998,7 @@ func TestToolFeedbackExplanationForToolCall_DoesNotReuseAnotherToolCallExplanati
 		{Role: "user", Content: "inspect the config and update the example"},
 	}
 
-	got := toolFeedbackExplanationForToolCall(response, response.ToolCalls[0], messages, 300)
+	got := toolFeedbackExplanationForToolCall(response, response.ToolCalls[0], messages)
 	want := utils.ToolFeedbackContinuationHint + ": inspect the config and update the example"
 	if got != want {
 		t.Fatalf("toolFeedbackExplanationForToolCall() = %q, want %q", got, want)
@@ -1958,13 +2017,42 @@ func TestToolFeedbackExplanationFromResponse_DoesNotUseReasoningContent(t *testi
 		{Role: "tool", Content: "tool output", ToolCallID: "call_1"},
 	}
 
-	got := toolFeedbackExplanationFromResponse(response, messages, 300)
+	got := toolFeedbackExplanationFromResponse(response, messages)
 	want := utils.ToolFeedbackContinuationHint + ": Inspect README.md and update the config example."
 	if got != want {
 		t.Fatalf("toolFeedbackExplanationFromResponse() = %q, want latest user content fallback", got)
 	}
 }
 
+func TestToolFeedbackExplanationForToolCall_DoesNotTruncateLongExplanation(t *testing.T) {
+	explanation := "Read README.md first to confirm the current project structure before editing the config example."
+	response := &providers.LLMResponse{
+		ToolCalls: []providers.ToolCall{{
+			ID:   "call_1",
+			Name: "read_file",
+			ExtraContent: &providers.ExtraContent{
+				ToolFeedbackExplanation: explanation,
+			},
+		}},
+	}
+
+	got := toolFeedbackExplanationForToolCall(response, response.ToolCalls[0], nil)
+	if got != explanation {
+		t.Fatalf("toolFeedbackExplanationForToolCall() = %q, want full explanation", got)
+	}
+}
+
+func TestToolFeedbackArgsPreview_UsesJSONAndTruncates(t *testing.T) {
+	got := toolFeedbackArgsPreview(map[string]any{
+		"path":  "README.md",
+		"limit": 42,
+	}, 128)
+	want := "{\n  \"limit\": 42,\n  \"path\": \"README.md\"\n}"
+	if got != want {
+		t.Fatalf("toolFeedbackArgsPreview() = %q, want %q", got, want)
+	}
+}
+
 type picoInterleavedContentProvider struct {
 	calls int
 }
@@ -1999,6 +2087,43 @@ func (m *picoInterleavedContentProvider) GetDefaultModel() string {
 	return "pico-interleaved-content-model"
 }
 
+type picoDistinctToolCallContentProvider struct {
+	calls int
+}
+
+func (m *picoDistinctToolCallContentProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	if m.calls == 1 {
+		return &providers.LLMResponse{
+			Content: "intermediate model text",
+			ToolCalls: []providers.ToolCall{{
+				ID:        "call_tool_limit_test",
+				Type:      "function",
+				Name:      "tool_limit_test_tool",
+				Arguments: map[string]any{"value": "x"},
+				ExtraContent: &providers.ExtraContent{
+					ToolFeedbackExplanation: "Read the file before replying.",
+				},
+			}},
+		}, nil
+	}
+
+	return &providers.LLMResponse{
+		Content:   "final model text",
+		ToolCalls: []providers.ToolCall{},
+	}, nil
+}
+
+func (m *picoDistinctToolCallContentProvider) GetDefaultModel() string {
+	return "pico-distinct-tool-call-content-model"
+}
+
 type toolLimitOnlyProvider struct{}
 
 func (m *toolLimitOnlyProvider) Chat(
@@ -3922,6 +4047,7 @@ func TestProcessMessage_PublishesToolFeedbackWhenEnabled(t *testing.T) {
 
 	select {
 	case outbound := <-msgBus.OutboundChan():
+		escapedHeartbeatFile := strings.ReplaceAll(heartbeatFile, `\`, `\\`)
 		if outbound.Channel != "telegram" {
 			t.Fatalf("tool feedback channel = %q, want %q", outbound.Channel, "telegram")
 		}
@@ -3940,6 +4066,12 @@ func TestProcessMessage_PublishesToolFeedbackWhenEnabled(t *testing.T) {
 		if !strings.Contains(outbound.Content, "check tool feedback") {
 			t.Fatalf("tool feedback content = %q, want current user intent fallback", outbound.Content)
 		}
+		if !strings.Contains(outbound.Content, "\"path\":") {
+			t.Fatalf("tool feedback content = %q, want serialized tool arguments", outbound.Content)
+		}
+		if !strings.Contains(outbound.Content, escapedHeartbeatFile) {
+			t.Fatalf("tool feedback content = %q, want tool argument value", outbound.Content)
+		}
 		if strings.Contains(outbound.Content, "Previous turn explanation") {
 			t.Fatalf("tool feedback content = %q, want no previous assistant fallback", outbound.Content)
 		}
@@ -3957,6 +4089,182 @@ func TestProcessMessage_PublishesToolFeedbackWhenEnabled(t *testing.T) {
 	}
 }
 
+func TestProcessMessage_PersistsReasoningContentInSessionHistory(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &reasoningContentProvider{
+		response:         "final answer",
+		reasoningContent: "thinking trace",
+	}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "pico",
+		SenderID: "user1",
+		ChatID:   "pico:test-session",
+		Content:  "hello",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "final answer" {
+		t.Fatalf("processMessage() response = %q, want %q", response, "final answer")
+	}
+
+	store := al.GetRegistry().GetDefaultAgent().Sessions
+	sessionKeys := store.ListSessions()
+	if len(sessionKeys) != 1 {
+		t.Fatalf("session keys = %v, want exactly 1 active session", sessionKeys)
+	}
+	history := store.GetHistory(sessionKeys[0])
+	if len(history) < 2 {
+		t.Fatalf("session history len = %d, want at least 2", len(history))
+	}
+
+	last := history[len(history)-1]
+	if last.Role != "assistant" {
+		t.Fatalf("last message role = %q, want assistant", last.Role)
+	}
+	if last.Content != "final answer" {
+		t.Fatalf("last message content = %q, want %q", last.Content, "final answer")
+	}
+	if last.ReasoningContent != "thinking trace" {
+		t.Fatalf("last message reasoning_content = %q, want %q", last.ReasoningContent, "thinking trace")
+	}
+}
+
+func TestProcessMessage_PersistsReasoningToolResponseAsSingleAssistantRecord(t *testing.T) {
+	tmpDir := t.TempDir()
+	inspectPath := filepath.Join(tmpDir, "inspect.txt")
+	if err := os.WriteFile(inspectPath, []byte("inspect me"), 0o644); err != nil {
+		t.Fatalf("WriteFile(inspectPath) error = %v", err)
+	}
+
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.Workspace = tmpDir
+	cfg.Agents.Defaults.ModelName = "test-model"
+	cfg.Agents.Defaults.MaxTokens = 4096
+	cfg.Agents.Defaults.MaxToolIterations = 10
+
+	msgBus := bus.NewMessageBus()
+	provider := &reasoningVisibleToolProvider{filePath: inspectPath}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "DONE" {
+		t.Fatalf("processMessage() response = %q, want %q", response, "DONE")
+	}
+
+	store := al.GetRegistry().GetDefaultAgent().Sessions
+	sessionKeys := store.ListSessions()
+	if len(sessionKeys) != 1 {
+		t.Fatalf("session keys = %v, want exactly 1 active session", sessionKeys)
+	}
+
+	history := store.GetHistory(sessionKeys[0])
+	if len(history) < 3 {
+		t.Fatalf("session history len = %d, want at least 3", len(history))
+	}
+
+	var assistantWithToolCall *providers.Message
+	for i := range history {
+		msg := history[i]
+		if msg.Role == "assistant" && len(msg.ToolCalls) > 0 {
+			assistantWithToolCall = &msg
+			break
+		}
+	}
+	if assistantWithToolCall == nil {
+		t.Fatal("expected assistant history record with tool_calls")
+	}
+	if assistantWithToolCall.Content != "I'll inspect that file now." {
+		t.Fatalf("assistant content = %q, want %q", assistantWithToolCall.Content, "I'll inspect that file now.")
+	}
+	if assistantWithToolCall.ReasoningContent != "Read the file before answering." {
+		t.Fatalf("assistant reasoning_content = %q, want preserved", assistantWithToolCall.ReasoningContent)
+	}
+	if len(assistantWithToolCall.ToolCalls) != 1 {
+		t.Fatalf("assistant tool calls = %+v, want single read_file tool", assistantWithToolCall.ToolCalls)
+	}
+	if got := providers.NormalizeToolCall(assistantWithToolCall.ToolCalls[0]).Name; got != "read_file" {
+		t.Fatalf("assistant tool calls = %+v, want single read_file tool", assistantWithToolCall.ToolCalls)
+	}
+
+	sessionDir := filepath.Join(tmpDir, "sessions")
+	entries, err := os.ReadDir(sessionDir)
+	if err != nil {
+		t.Fatalf("ReadDir(%q) error = %v", sessionDir, err)
+	}
+
+	var jsonlPath string
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".jsonl") {
+			continue
+		}
+		jsonlPath = filepath.Join(sessionDir, entry.Name())
+		break
+	}
+	if jsonlPath == "" {
+		t.Fatal("expected session jsonl file to be created")
+	}
+
+	data, err := os.ReadFile(jsonlPath)
+	if err != nil {
+		t.Fatalf("ReadFile(%q) error = %v", jsonlPath, err)
+	}
+
+	lines := strings.Split(strings.TrimSpace(string(data)), "\n")
+	if len(lines) < 3 {
+		t.Fatalf("jsonl lines = %d, want at least 3", len(lines))
+	}
+
+	matchingRecords := 0
+	for _, line := range lines {
+		var msg providers.Message
+		if err := json.Unmarshal([]byte(line), &msg); err != nil {
+			t.Fatalf("Unmarshal(jsonl line) error = %v", err)
+		}
+		if msg.Role != "assistant" {
+			continue
+		}
+		if msg.Content == "I'll inspect that file now." || msg.ReasoningContent == "Read the file before answering." {
+			matchingRecords++
+			toolName := ""
+			if len(msg.ToolCalls) == 1 {
+				toolName = providers.NormalizeToolCall(msg.ToolCalls[0]).Name
+			}
+			if msg.Content != "I'll inspect that file now." ||
+				msg.ReasoningContent != "Read the file before answering." ||
+				len(msg.ToolCalls) != 1 ||
+				toolName != "read_file" {
+				t.Fatalf("assistant jsonl record = %+v, want content+reasoning+tool_calls in one line", msg)
+			}
+		}
+	}
+	if matchingRecords != 1 {
+		t.Fatalf("matching assistant jsonl records = %d, want exactly 1 canonical assistant record", matchingRecords)
+	}
+}
+
 func TestProcessMessage_DoesNotLeakReasoningContentInToolFeedback(t *testing.T) {
 	tmpDir := t.TempDir()
 	heartbeatFile := filepath.Join(tmpDir, "tool-feedback-reasoning.txt")
@@ -4003,6 +4311,7 @@ func TestProcessMessage_DoesNotLeakReasoningContentInToolFeedback(t *testing.T)
 
 	select {
 	case outbound := <-msgBus.OutboundChan():
+		escapedHeartbeatFile := strings.ReplaceAll(heartbeatFile, `\`, `\\`)
 		if !strings.Contains(outbound.Content, "`read_file`") {
 			t.Fatalf("tool feedback content = %q, want read_file summary", outbound.Content)
 		}
@@ -4012,6 +4321,12 @@ func TestProcessMessage_DoesNotLeakReasoningContentInToolFeedback(t *testing.T)
 		if !strings.Contains(outbound.Content, "check reasoning fallback") {
 			t.Fatalf("tool feedback content = %q, want current user intent fallback", outbound.Content)
 		}
+		if !strings.Contains(outbound.Content, "\"path\":") {
+			t.Fatalf("tool feedback content = %q, want serialized tool arguments", outbound.Content)
+		}
+		if !strings.Contains(outbound.Content, escapedHeartbeatFile) {
+			t.Fatalf("tool feedback content = %q, want tool argument value", outbound.Content)
+		}
 		if strings.Contains(outbound.Content, "Read README.md first") {
 			t.Fatalf("tool feedback content = %q, should not leak hidden reasoning", outbound.Content)
 		}
@@ -4143,7 +4458,7 @@ func TestRun_PicoPublishesAssistantContentDuringToolCallsWithoutFinalDuplicate(t
 	}
 
 	msgBus := bus.NewMessageBus()
-	provider := &picoInterleavedContentProvider{}
+	provider := &picoDistinctToolCallContentProvider{}
 	al := NewAgentLoop(cfg, msgBus, provider)
 
 	agent := al.GetRegistry().GetDefaultAgent()
@@ -4169,22 +4484,28 @@ func TestRun_PicoPublishesAssistantContentDuringToolCallsWithoutFinalDuplicate(t
 		t.Fatalf("PublishInbound() error = %v", err)
 	}
 
-	outputs := make([]string, 0, 2)
+	outputs := make([]bus.OutboundMessage, 0, 3)
 	deadline := time.After(2 * time.Second)
-	for len(outputs) < 2 {
+	for len(outputs) < 3 {
 		select {
 		case outbound := <-msgBus.OutboundChan():
-			outputs = append(outputs, outbound.Content)
+			outputs = append(outputs, outbound)
 		case <-deadline:
 			t.Fatalf("timed out waiting for pico outputs, got %v", outputs)
 		}
 	}
 
-	if outputs[0] != "intermediate model text" {
-		t.Fatalf("first outbound content = %q, want %q", outputs[0], "intermediate model text")
+	if outputs[0].Content != "intermediate model text" {
+		t.Fatalf("first outbound content = %q, want %q", outputs[0].Content, "intermediate model text")
 	}
-	if outputs[1] != "final model text" {
-		t.Fatalf("second outbound content = %q, want %q", outputs[1], "final model text")
+	if outputs[1].Context.Raw[metadataKeyMessageKind] != messageKindToolCalls {
+		t.Fatalf("second outbound = %+v, want tool_calls message", outputs[1])
+	}
+	if !strings.Contains(outputs[1].Context.Raw[metadataKeyToolCalls], "tool_limit_test_tool") {
+		t.Fatalf("second outbound tool_calls = %q, want tool name", outputs[1].Context.Raw[metadataKeyToolCalls])
+	}
+	if outputs[2].Content != "final model text" {
+		t.Fatalf("third outbound content = %q, want %q", outputs[2].Content, "final model text")
 	}
 
 	runCancel()
@@ -4299,22 +4620,28 @@ func TestRun_PicoToolFeedbackSuppressesDuplicateInterimAssistantContent(t *testi
 		t.Fatalf("PublishInbound() error = %v", err)
 	}
 
-	outputs := make([]string, 0, 2)
+	outputs := make([]bus.OutboundMessage, 0, 3)
 	deadline := time.After(2 * time.Second)
 	for len(outputs) < 2 {
 		select {
 		case outbound := <-msgBus.OutboundChan():
-			outputs = append(outputs, outbound.Content)
+			outputs = append(outputs, outbound)
 		case <-deadline:
 			t.Fatalf("timed out waiting for pico outputs, got %v", outputs)
 		}
 	}
 
-	if outputs[0] != "🔧 `tool_limit_test_tool`\nintermediate model text" {
-		t.Fatalf("first outbound content = %q, want tool feedback summary", outputs[0])
+	if outputs[0].Context.Raw[metadataKeyMessageKind] != messageKindToolCalls {
+		t.Fatalf("first outbound = %+v, want tool_calls message", outputs[0])
 	}
-	if outputs[1] != "final model text" {
-		t.Fatalf("second outbound content = %q, want %q", outputs[1], "final model text")
+	if outputs[0].Content != "" {
+		t.Fatalf("first outbound content = %q, want empty tool_calls content", outputs[0].Content)
+	}
+	if !strings.Contains(outputs[0].Context.Raw[metadataKeyToolCalls], "tool_limit_test_tool") {
+		t.Fatalf("first outbound tool_calls = %q, want tool name", outputs[0].Context.Raw[metadataKeyToolCalls])
+	}
+	if outputs[1].Content != "final model text" {
+		t.Fatalf("second outbound content = %q, want %q", outputs[1].Content, "final model text")
 	}
 
 	runCancel()
@@ -4334,7 +4661,7 @@ func TestRun_PicoToolFeedbackSuppressesDuplicateInterimAssistantContent(t *testi
 	}
 }
 
-func TestResolveMediaRefs_ResolvesToBase64(t *testing.T) {
+func TestResolveMediaRefs_ImageInjectsPathTag(t *testing.T) {
 	store := media.NewFileMediaStore()
 	dir := t.TempDir()
 
@@ -4362,15 +4689,110 @@ func TestResolveMediaRefs_ResolvesToBase64(t *testing.T) {
 	}
 	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
 
-	if len(result[0].Media) != 1 {
-		t.Fatalf("expected 1 resolved media, got %d", len(result[0].Media))
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media (images use path tags), got %d", len(result[0].Media))
 	}
-	if !strings.HasPrefix(result[0].Media[0], "data:image/png;base64,") {
-		t.Fatalf("expected data:image/png;base64, prefix, got %q", result[0].Media[0][:40])
+	localPath, _, _ := store.ResolveWithMeta(ref)
+	expectedContent := "describe this [image:" + localPath + "]"
+	if result[0].Content != expectedContent {
+		t.Fatalf("expected content %q, got %q", expectedContent, result[0].Content)
 	}
 }
 
-func TestResolveMediaRefs_SkipsOversizedFile(t *testing.T) {
+func TestResolveMediaRefs_ToolRoleImageAppendedAsUserMessage(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	pngPath := filepath.Join(dir, "tool-result.png")
+	pngHeader := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, // PNG signature
+		0x00, 0x00, 0x00, 0x0D, // IHDR length
+		0x49, 0x48, 0x44, 0x52, // "IHDR"
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02, // 1x1 RGB
+		0x00, 0x00, 0x00, // no interlace
+		0x90, 0x77, 0x53, 0xDE, // CRC
+	}
+	if err := os.WriteFile(pngPath, pngHeader, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	ref, _ := store.Store(pngPath, media.MediaMeta{}, "test")
+
+	messages := []providers.Message{
+		{Role: "tool", Content: "Image loaded", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	// Tool message should have path tag but no base64
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media in tool message, got %d", len(result[0].Media))
+	}
+	localPath, _, _ := store.ResolveWithMeta(ref)
+	if !strings.Contains(result[0].Content, "[image:"+localPath+"]") {
+		t.Fatalf("expected image path tag in tool content, got %q", result[0].Content)
+	}
+
+	// A synthetic user message with base64 should follow
+	if len(result) != 2 {
+		t.Fatalf("expected 2 messages (tool + synthetic user), got %d", len(result))
+	}
+	if result[1].Role != "user" {
+		t.Fatalf("expected synthetic message role=user, got %q", result[1].Role)
+	}
+	if len(result[1].Media) != 1 {
+		t.Fatalf("expected 1 base64 media in synthetic user message, got %d", len(result[1].Media))
+	}
+	if !strings.HasPrefix(result[1].Media[0], "data:image/png;base64,") {
+		t.Fatalf("expected data:image/png;base64, prefix, got %q", result[1].Media[0][:40])
+	}
+}
+
+func TestResolveMediaRefs_MultiToolCallPreservesOrdering(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	// Create image for tool #1
+	pngPath := filepath.Join(dir, "loaded.png")
+	pngHeader := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, // PNG signature
+		0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52, // IHDR
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02,
+		0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xDE,
+	}
+	os.WriteFile(pngPath, pngHeader, 0o644)
+	imgRef, _ := store.Store(pngPath, media.MediaMeta{}, "test")
+
+	// Simulate: assistant called load_image + read_file, two tool results follow
+	messages := []providers.Message{
+		{Role: "assistant", Content: "Let me load the image and read the file."},
+		{Role: "tool", Content: "Image loaded [image: photo]", Media: []string{imgRef}},
+		{Role: "tool", Content: "file contents here"},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	// assistant, tool#1, tool#2 must remain contiguous — no user in between
+	if result[0].Role != "assistant" {
+		t.Fatalf("result[0] expected assistant, got %q", result[0].Role)
+	}
+	if result[1].Role != "tool" {
+		t.Fatalf("result[1] expected tool, got %q", result[1].Role)
+	}
+	if result[2].Role != "tool" {
+		t.Fatalf("result[2] expected tool, got %q", result[2].Role)
+	}
+
+	// Synthetic user message should come AFTER the tool block
+	if len(result) != 4 {
+		t.Fatalf("expected 4 messages (assistant + 2 tool + synthetic user), got %d", len(result))
+	}
+	if result[3].Role != "user" {
+		t.Fatalf("result[3] expected user, got %q", result[3].Role)
+	}
+	if len(result[3].Media) != 1 || !strings.HasPrefix(result[3].Media[0], "data:image/png;base64,") {
+		t.Fatal("expected synthetic user message to contain base64 image")
+	}
+}
+
+func TestResolveMediaRefs_OversizedImageSkipsBase64KeepsPathTag(t *testing.T) {
 	store := media.NewFileMediaStore()
 	dir := t.TempDir()
 
@@ -4392,6 +4814,11 @@ func TestResolveMediaRefs_SkipsOversizedFile(t *testing.T) {
 	if len(result[0].Media) != 0 {
 		t.Fatalf("expected 0 media (oversized), got %d", len(result[0].Media))
 	}
+	localPath, _, _ := store.ResolveWithMeta(ref)
+	expected := "hi [image:" + localPath + "]"
+	if result[0].Content != expected {
+		t.Fatalf("expected content %q, got %q", expected, result[0].Content)
+	}
 }
 
 func TestResolveMediaRefs_UnknownTypeInjectsPath(t *testing.T) {
@@ -4469,11 +4896,13 @@ func TestResolveMediaRefs_UsesMetaContentType(t *testing.T) {
 	}
 	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
 
-	if len(result[0].Media) != 1 {
-		t.Fatalf("expected 1 media, got %d", len(result[0].Media))
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media (images use path tags), got %d", len(result[0].Media))
 	}
-	if !strings.HasPrefix(result[0].Media[0], "data:image/jpeg;base64,") {
-		t.Fatalf("expected jpeg prefix, got %q", result[0].Media[0][:30])
+	localPath, _, _ := store.ResolveWithMeta(ref)
+	expectedContent := "hi [image:" + localPath + "]"
+	if result[0].Content != expectedContent {
+		t.Fatalf("expected content %q, got %q", expectedContent, result[0].Content)
 	}
 }
 
@@ -4563,6 +4992,98 @@ func TestResolveMediaRefs_NoGenericTagAppendsPath(t *testing.T) {
 	}
 }
 
+func TestInjectPathTags_HandlesVariousChannelPlaceholders(t *testing.T) {
+	cases := []struct {
+		name    string
+		content string
+		tag     string
+		want    string
+	}{
+		// Telegram / Feishu format
+		{"image_photo", "[image: photo]", "[image:/tmp/p.png]", "[image:/tmp/p.png]"},
+		// WeCom / WeChat / Line format
+		{"bare_image", "[image]", "[image:/tmp/p.png]", "[image:/tmp/p.png]"},
+		// QQ / Discord format with filename
+		{"image_filename", "[image: pic.jpg]", "[image:/tmp/p.png]", "[image:/tmp/p.png]"},
+		{"audio_with_filename", "[audio: voice.m4a]", "[audio:/tmp/a.m4a]", "[audio:/tmp/a.m4a]"},
+		{"bare_audio", "[audio]", "[audio:/tmp/a.m4a]", "[audio:/tmp/a.m4a]"},
+		{"bare_video", "[video]", "[video:/tmp/v.mp4]", "[video:/tmp/v.mp4]"},
+		{"bare_file", "[file]", "[file:/tmp/f.pdf]", "[file:/tmp/f.pdf]"},
+		// Mixed surrounding text
+		{
+			"with_text",
+			"hello [image] world",
+			"[image:/tmp/p.png]",
+			"hello [image:/tmp/p.png] world",
+		},
+		// No placeholder — append
+		{"no_placeholder", "hello world", "[image:/tmp/p.png]", "hello world [image:/tmp/p.png]"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := injectPathTags(tc.content, []string{tc.tag})
+			if got != tc.want {
+				t.Errorf("expected %q, got %q", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestInjectPathTags_DoesNotReplacePathTag(t *testing.T) {
+	// If content already contains a path tag, we must not touch it.
+	content := "see [image:/already/placed.png] thanks"
+	got := injectPathTags(content, []string{"[image:/new/path.png]"})
+	want := "see [image:/already/placed.png] thanks [image:/new/path.png]"
+	if got != want {
+		t.Fatalf("expected %q, got %q", want, got)
+	}
+}
+
+func TestInjectPathTags_PrependsForJSONContent(t *testing.T) {
+	jsonContent := `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`
+	got := injectPathTags(jsonContent, []string{"[image:/tmp/photo.png]"})
+	want := "[image:/tmp/photo.png]\n" + jsonContent
+	if got != want {
+		t.Fatalf("expected tag prepended to JSON, got %q", got)
+	}
+}
+
+func TestInjectPathTags_BracketTextNotTreatedAsJSON(t *testing.T) {
+	content := "[update] see attached report"
+	got := injectPathTags(content, []string{"[file:/tmp/report.pdf]"})
+	want := "[update] see attached report [file:/tmp/report.pdf]"
+	if got != want {
+		t.Fatalf("expected tag appended to bracket text, got %q", got)
+	}
+}
+
+func TestResolveMediaRefs_JSONContentPrependsPathTag(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	pngPath := filepath.Join(dir, "card_img.png")
+	pngHeader := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
+		0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52,
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02,
+		0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xDE,
+	}
+	os.WriteFile(pngPath, pngHeader, 0o644)
+	ref, _ := store.Store(pngPath, media.MediaMeta{ContentType: "image/png"}, "test")
+
+	jsonContent := `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`
+	messages := []providers.Message{
+		{Role: "user", Content: jsonContent, Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	want := "[image:" + pngPath + "]\n" + jsonContent
+	if result[0].Content != want {
+		t.Fatalf("expected path tag prepended to JSON content, got %q", result[0].Content)
+	}
+}
+
 func TestResolveMediaRefs_EmptyContentGetsPathTag(t *testing.T) {
 	store := media.NewFileMediaStore()
 	dir := t.TempDir()
@@ -4606,13 +5127,12 @@ func TestResolveMediaRefs_MixedImageAndFile(t *testing.T) {
 	}
 	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
 
-	if len(result[0].Media) != 1 {
-		t.Fatalf("expected 1 media (image only), got %d", len(result[0].Media))
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media (all types use path tags), got %d", len(result[0].Media))
 	}
-	if !strings.HasPrefix(result[0].Media[0], "data:image/png;base64,") {
-		t.Fatal("expected image to be base64 encoded")
-	}
-	expectedContent := "check these [file:" + pdfPath + "]"
+	imgLocalPath, _, _ := store.ResolveWithMeta(imgRef)
+	pdfLocalPath, _, _ := store.ResolveWithMeta(fileRef)
+	expectedContent := "check these [file:" + pdfLocalPath + "] [image:" + imgLocalPath + "]"
 	if result[0].Content != expectedContent {
 		t.Fatalf("expected content %q, got %q", expectedContent, result[0].Content)
 	}

pkg/agent/agent_utils.go

@@ -4,7 +4,9 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"maps"
 	"path/filepath"
 	"strings"
 	"time"
@@ -113,7 +115,6 @@ func latestUserContent(messages []providers.Message) string {
 func toolFeedbackExplanationFromResponse(
 	response *providers.LLMResponse,
 	messages []providers.Message,
-	maxLen int,
 ) string {
 	if response == nil {
 		return ""
@@ -125,7 +126,7 @@ func toolFeedbackExplanationFromResponse(
 	if explanation == "" {
 		explanation = toolFeedbackExplanationFromMessages(messages)
 	}
-	return utils.Truncate(explanation, maxLen)
+	return explanation
 }
 
 func toolFeedbackExplanationFromToolCalls(toolCalls []providers.ToolCall) string {
@@ -144,22 +145,21 @@ func toolFeedbackExplanationForToolCall(
 	response *providers.LLMResponse,
 	toolCall providers.ToolCall,
 	messages []providers.Message,
-	maxLen int,
 ) string {
 	if toolCall.ExtraContent != nil {
 		if explanation := strings.TrimSpace(toolCall.ExtraContent.ToolFeedbackExplanation); explanation != "" {
-			return utils.Truncate(explanation, maxLen)
+			return explanation
 		}
 	}
 	if response == nil {
-		return utils.Truncate(toolFeedbackExplanationFromMessages(messages), maxLen)
+		return toolFeedbackExplanationFromMessages(messages)
 	}
 
 	explanation := strings.TrimSpace(response.Content)
 	if explanation == "" {
 		explanation = toolFeedbackExplanationFromMessages(messages)
 	}
-	return utils.Truncate(explanation, maxLen)
+	return explanation
 }
 
 func toolFeedbackExplanationFromMessages(messages []providers.Message) string {
@@ -170,6 +170,18 @@ func toolFeedbackExplanationFromMessages(messages []providers.Message) string {
 	return ""
 }
 
+func toolFeedbackArgsPreview(args map[string]any, maxLen int) string {
+	if args == nil {
+		args = map[string]any{}
+	}
+
+	argsJSON, err := json.MarshalIndent(args, "", "  ")
+	if err != nil {
+		return utils.Truncate(fmt.Sprintf("%v", args), maxLen)
+	}
+	return utils.Truncate(string(argsJSON), maxLen)
+}
+
 func shouldPublishToolFeedback(cfg *config.Config, ts *turnState) bool {
 	if ts == nil || ts.channel == "" || ts.opts.SuppressToolFeedback {
 		return false
@@ -465,17 +477,28 @@ func sideQuestionResponseContent(response *providers.LLMResponse) string {
 	if response == nil {
 		return ""
 	}
-	if response.Content != "" {
+	if strings.TrimSpace(response.Content) != "" {
 		return response.Content
 	}
-	return response.ReasoningContent
+	return responseReasoningContent(response)
+}
+
+func responseReasoningContent(response *providers.LLMResponse) string {
+	if response == nil {
+		return ""
+	}
+	if strings.TrimSpace(response.Reasoning) != "" {
+		return response.Reasoning
+	}
+	if strings.TrimSpace(response.ReasoningContent) != "" {
+		return response.ReasoningContent
+	}
+	return ""
 }
 
 func shallowCloneLLMOptions(opts map[string]any) map[string]any {
 	clone := make(map[string]any, len(opts))
-	for k, v := range opts {
-		clone[k] = v
-	}
+	maps.Copy(clone, opts)
 	return clone
 }
 

pkg/agent/context.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"io/fs"
@@ -21,12 +22,11 @@ import (
 )
 
 type ContextBuilder struct {
-	workspace          string
-	skillsLoader       *skills.SkillsLoader
-	memory             *MemoryStore
-	toolDiscoveryBM25  bool
-	toolDiscoveryRegex bool
-	splitOnMarker      bool
+	workspace      string
+	skillsLoader   *skills.SkillsLoader
+	memory         *MemoryStore
+	splitOnMarker  bool
+	promptRegistry *PromptRegistry
 
 	// Cache for system prompt to avoid rebuilding on every call.
 	// This fixes issue #607: repeated reprocessing of the entire context.
@@ -48,8 +48,16 @@ type ContextBuilder struct {
 }
 
 func (cb *ContextBuilder) WithToolDiscovery(useBM25, useRegex bool) *ContextBuilder {
-	cb.toolDiscoveryBM25 = useBM25
-	cb.toolDiscoveryRegex = useRegex
+	if useBM25 || useRegex {
+		if err := cb.RegisterPromptContributor(toolDiscoveryPromptContributor{
+			useBM25:  useBM25,
+			useRegex: useRegex,
+		}); err != nil {
+			logger.WarnCF("agent", "Failed to register tool discovery prompt contributor", map[string]any{
+				"error": err.Error(),
+			})
+		}
+	}
 	return cb
 }
 
@@ -73,15 +81,38 @@ func NewContextBuilder(workspace string) *ContextBuilder {
 	globalSkillsDir := filepath.Join(getGlobalConfigDir(), "skills")
 
 	return &ContextBuilder{
-		workspace:    workspace,
-		skillsLoader: skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir),
-		memory:       NewMemoryStore(workspace),
+		workspace:      workspace,
+		skillsLoader:   skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir),
+		memory:         NewMemoryStore(workspace),
+		promptRegistry: NewPromptRegistry(),
 	}
 }
 
+func (cb *ContextBuilder) RegisterPromptSource(desc PromptSourceDescriptor) error {
+	err := cb.promptRegistryOrDefault().RegisterSource(desc)
+	if err == nil {
+		cb.InvalidateCache()
+	}
+	return err
+}
+
+func (cb *ContextBuilder) RegisterPromptContributor(contributor PromptContributor) error {
+	err := cb.promptRegistryOrDefault().RegisterContributor(contributor)
+	if err == nil {
+		cb.InvalidateCache()
+	}
+	return err
+}
+
+func (cb *ContextBuilder) promptRegistryOrDefault() *PromptRegistry {
+	if cb.promptRegistry == nil {
+		cb.promptRegistry = NewPromptRegistry()
+	}
+	return cb.promptRegistry
+}
+
 func (cb *ContextBuilder) getIdentity() string {
 	workspacePath, _ := filepath.Abs(filepath.Join(cb.workspace))
-	toolDiscovery := cb.getDiscoveryRule()
 	version := config.FormatVersion()
 
 	return fmt.Sprintf(
@@ -103,22 +134,20 @@ Your workspace is at: %s
 
 3. **Memory** - When interacting with me if something seems memorable, update %s/memory/MEMORY.md
 
-4. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.
-
-%s`,
-		version, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath, toolDiscovery)
+4. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.`,
+		version, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath)
 }
 
-func (cb *ContextBuilder) getDiscoveryRule() string {
-	if !cb.toolDiscoveryBM25 && !cb.toolDiscoveryRegex {
+func formatToolDiscoveryRule(useBM25, useRegex bool) string {
+	if !useBM25 && !useRegex {
 		return ""
 	}
 
 	var toolNames []string
-	if cb.toolDiscoveryBM25 {
+	if useBM25 {
 		toolNames = append(toolNames, `"tool_search_tool_bm25"`)
 	}
-	if cb.toolDiscoveryRegex {
+	if useRegex {
 		toolNames = append(toolNames, `"tool_search_tool_regex"`)
 	}
 
@@ -129,43 +158,103 @@ func (cb *ContextBuilder) getDiscoveryRule() string {
 }
 
 func (cb *ContextBuilder) BuildSystemPrompt() string {
-	parts := []string{}
+	return renderPromptPartsLegacy(cb.BuildSystemPromptParts())
+}
+
+func (cb *ContextBuilder) BuildSystemPromptParts() []PromptPart {
+	stack := NewPromptStack(cb.promptRegistryOrDefault())
+	add := func(part PromptPart) {
+		if err := stack.Add(part); err != nil {
+			logger.WarnCF("agent", "Skipping invalid prompt part", map[string]any{
+				"id":     part.ID,
+				"layer":  part.Layer,
+				"slot":   part.Slot,
+				"source": part.Source.ID,
+				"error":  err.Error(),
+			})
+		}
+	}
 
 	// Core identity section
-	parts = append(parts, cb.getIdentity())
+	add(PromptPart{
+		ID:      "kernel.identity",
+		Layer:   PromptLayerKernel,
+		Slot:    PromptSlotIdentity,
+		Source:  PromptSource{ID: PromptSourceKernel, Name: "identity"},
+		Title:   "picoclaw identity",
+		Content: cb.getIdentity(),
+		Stable:  true,
+		Cache:   PromptCacheEphemeral,
+	})
 
 	// Bootstrap files
 	bootstrapContent := cb.LoadBootstrapFiles()
 	if bootstrapContent != "" {
-		parts = append(parts, bootstrapContent)
+		add(PromptPart{
+			ID:      "instruction.workspace",
+			Layer:   PromptLayerInstruction,
+			Slot:    PromptSlotWorkspace,
+			Source:  PromptSource{ID: PromptSourceWorkspace, Name: "workspace"},
+			Title:   "workspace instructions",
+			Content: bootstrapContent,
+			Stable:  true,
+			Cache:   PromptCacheEphemeral,
+		})
 	}
 
 	// Skills - show summary, AI can read full content with read_file tool
 	skillsSummary := cb.skillsLoader.BuildSkillsSummary()
 	if skillsSummary != "" {
-		parts = append(parts, fmt.Sprintf(`# Skills
+		add(PromptPart{
+			ID:     "capability.skill_catalog",
+			Layer:  PromptLayerCapability,
+			Slot:   PromptSlotSkillCatalog,
+			Source: PromptSource{ID: PromptSourceSkillCatalog, Name: "skill:index"},
+			Title:  "skill catalog",
+			Content: fmt.Sprintf(`# Skills
 
 The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
 
-%s`, skillsSummary))
+%s`, skillsSummary),
+			Stable: true,
+			Cache:  PromptCacheEphemeral,
+		})
 	}
 
 	// Memory context
 	memoryContext := cb.memory.GetMemoryContext()
 	if memoryContext != "" {
-		parts = append(parts, "# Memory\n\n"+memoryContext)
+		add(PromptPart{
+			ID:      "context.memory",
+			Layer:   PromptLayerContext,
+			Slot:    PromptSlotMemory,
+			Source:  PromptSource{ID: PromptSourceMemory, Name: "memory:workspace"},
+			Title:   "memory",
+			Content: "# Memory\n\n" + memoryContext,
+			Stable:  true,
+			Cache:   PromptCacheEphemeral,
+		})
 	}
 
 	// Multi-Message Sending (if enabled)
 	if cb.splitOnMarker {
-		parts = append(parts, `# MULTI-MESSAGE OUTPUT
+		add(PromptPart{
+			ID:     "context.output_policy.split_on_marker",
+			Layer:  PromptLayerContext,
+			Slot:   PromptSlotOutput,
+			Source: PromptSource{ID: PromptSourceOutputPolicy, Name: "split_on_marker"},
+			Title:  "multi-message output policy",
+			Content: `# MULTI-MESSAGE OUTPUT
 You MUST frequently use <|[SPLIT]|> to break your responses into multiple short messages. NEVER output a single long wall of text. Actively split distinct concepts or parts. Example: Message part 1<|[SPLIT]|>Message part 2<|[SPLIT]|>Message part 3
 
-Each part separated by the marker will be sent as an independent message.`)
+Each part separated by the marker will be sent as an independent message.`,
+			Stable: true,
+			Cache:  PromptCacheEphemeral,
+		})
 	}
 
-	// Join with "---" separator
-	return strings.Join(parts, "\n\n---\n\n")
+	stack.Seal()
+	return stack.Parts()
 }
 
 // BuildSystemPromptWithCache returns the cached system prompt if available
@@ -230,6 +319,19 @@ func (cb *ContextBuilder) EstimateSystemTokens(summary string, activeSkills []st
 		totalChars += 7 // separator \n\n---\n\n
 	}
 
+	if contributedParts, err := cb.promptRegistryOrDefault().Collect(context.Background(), PromptBuildRequest{
+		Summary:      summary,
+		ActiveSkills: append([]string(nil), activeSkills...),
+	}); err == nil {
+		for _, part := range contributedParts {
+			if strings.TrimSpace(part.Content) == "" {
+				continue
+			}
+			totalChars += utf8.RuneCountInString(part.Content)
+			totalChars += 7 // separator
+		}
+	}
+
 	if summary != "" {
 		// Matches the CONTEXT_SUMMARY: prefix added in BuildMessages
 		const summaryPrefix = "CONTEXT_SUMMARY: The following is an approximate summary of prior conversation " +
@@ -548,6 +650,20 @@ func (cb *ContextBuilder) BuildMessages(
 	channel, chatID, senderID, senderDisplayName string,
 	activeSkills ...string,
 ) []providers.Message {
+	return cb.BuildMessagesFromPrompt(PromptBuildRequest{
+		History:           history,
+		Summary:           summary,
+		CurrentMessage:    currentMessage,
+		Media:             media,
+		Channel:           channel,
+		ChatID:            chatID,
+		SenderID:          senderID,
+		SenderDisplayName: senderDisplayName,
+		ActiveSkills:      append([]string(nil), activeSkills...),
+	})
+}
+
+func (cb *ContextBuilder) BuildMessagesFromPrompt(req PromptBuildRequest) []providers.Message {
 	messages := []providers.Message{}
 
 	// The static part (identity, bootstrap, skills, memory) is cached locally to
@@ -562,7 +678,7 @@ func (cb *ContextBuilder) BuildMessages(
 	staticPrompt := cb.BuildSystemPromptWithCache()
 
 	// Build short dynamic context (time, runtime, session) — changes per request
-	dynamicCtx := cb.buildDynamicContext(channel, chatID, senderID, senderDisplayName)
+	dynamicCtx := cb.buildDynamicContext(req.Channel, req.ChatID, req.SenderID, req.SenderDisplayName)
 
 	// Compose a single system message: static (cached) + dynamic + optional summary.
 	// Keeping all system content in one message ensures every provider adapter can
@@ -573,25 +689,77 @@ func (cb *ContextBuilder) BuildMessages(
 	// cache-aware adapters (Anthropic) can set per-block cache_control.
 	// The static block is marked "ephemeral" — its prefix hash is stable
 	// across requests, enabling LLM-side KV cache reuse.
-	stringParts := []string{staticPrompt, dynamicCtx}
+	stringParts := []string{staticPrompt}
 
 	contentBlocks := []providers.ContentBlock{
-		{Type: "text", Text: staticPrompt, CacheControl: &providers.CacheControl{Type: "ephemeral"}},
-		{Type: "text", Text: dynamicCtx},
+		promptContentBlock(PromptPart{
+			ID:      "kernel.static",
+			Layer:   PromptLayerKernel,
+			Slot:    PromptSlotIdentity,
+			Source:  PromptSource{ID: PromptSourceKernel, Name: "static"},
+			Content: staticPrompt,
+		}, &providers.CacheControl{Type: "ephemeral"}),
 	}
 
-	if skillsText := cb.buildActiveSkillsContext(activeSkills); skillsText != "" {
-		stringParts = append(stringParts, skillsText)
-		contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: skillsText})
+	promptParts := append([]PromptPart(nil), req.Overlays...)
+	promptParts = append(promptParts, cb.buildActiveSkillsPromptParts(req.ActiveSkills)...)
+	if contributedParts, err := cb.promptRegistryOrDefault().Collect(context.Background(), req); err != nil {
+		logger.WarnCF("agent", "Prompt contributor collection failed", map[string]any{
+			"error": err.Error(),
+		})
+	} else {
+		promptParts = append(promptParts, contributedParts...)
 	}
 
-	if summary != "" {
-		summaryText := fmt.Sprintf(
-			"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
-				"for reference only. It may be incomplete or outdated — always defer to explicit instructions.\n\n%s",
-			summary)
-		stringParts = append(stringParts, summaryText)
-		contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: summaryText})
+	if len(promptParts) > 0 {
+		for _, overlay := range sortPromptParts(promptParts) {
+			if strings.TrimSpace(overlay.Content) == "" {
+				continue
+			}
+			if err := cb.promptRegistryOrDefault().ValidatePart(overlay); err != nil {
+				logger.WarnCF("agent", "Skipping invalid prompt overlay", map[string]any{
+					"id":     overlay.ID,
+					"layer":  overlay.Layer,
+					"slot":   overlay.Slot,
+					"source": overlay.Source.ID,
+					"error":  err.Error(),
+				})
+				continue
+			}
+			stringParts = append(stringParts, overlay.Content)
+			contentBlocks = append(contentBlocks, promptContentBlock(overlay, nil))
+		}
+	}
+
+	runtimePart := PromptPart{
+		ID:      "context.runtime",
+		Layer:   PromptLayerContext,
+		Slot:    PromptSlotRuntime,
+		Source:  PromptSource{ID: PromptSourceRuntime, Name: "runtime"},
+		Title:   "runtime context",
+		Content: dynamicCtx,
+		Stable:  false,
+		Cache:   PromptCacheNone,
+	}
+	stringParts = append(stringParts, dynamicCtx)
+	contentBlocks = append(contentBlocks, promptContentBlock(runtimePart, nil))
+
+	if req.Summary != "" {
+		summaryPart := PromptPart{
+			ID:     "context.summary",
+			Layer:  PromptLayerContext,
+			Slot:   PromptSlotSummary,
+			Source: PromptSource{ID: PromptSourceSummary, Name: "context.summary"},
+			Title:  "context summary",
+			Content: fmt.Sprintf(
+				"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
+					"for reference only. It may be incomplete or outdated — always defer to explicit instructions.\n\n%s",
+				req.Summary),
+			Stable: false,
+			Cache:  PromptCacheNone,
+		}
+		stringParts = append(stringParts, summaryPart.Content)
+		contentBlocks = append(contentBlocks, promptContentBlock(summaryPart, nil))
 	}
 
 	fullSystemPrompt := strings.Join(stringParts, "\n\n---\n\n")
@@ -608,7 +776,8 @@ func (cb *ContextBuilder) BuildMessages(
 			"static_chars":  len(staticPrompt),
 			"dynamic_chars": len(dynamicCtx),
 			"total_chars":   len(fullSystemPrompt),
-			"has_summary":   summary != "",
+			"has_summary":   req.Summary != "",
+			"overlays":      len(req.Overlays),
 			"cached":        isCached,
 		})
 
@@ -619,7 +788,7 @@ func (cb *ContextBuilder) BuildMessages(
 			"preview": preview,
 		})
 
-	history = sanitizeHistoryForProvider(history)
+	history := sanitizeHistoryForProvider(req.History)
 
 	// Single system message containing all context — compatible with all providers.
 	// SystemParts enables cache-aware adapters to set per-block cache_control;
@@ -636,15 +805,8 @@ func (cb *ContextBuilder) BuildMessages(
 	// Add current user message. Media-only turns must still be preserved so
 	// multimodal providers receive the uploaded image even when the user sends
 	// no accompanying text.
-	if strings.TrimSpace(currentMessage) != "" || len(media) > 0 {
-		msg := providers.Message{
-			Role:    "user",
-			Content: currentMessage,
-		}
-		if len(media) > 0 {
-			msg.Media = append([]string(nil), media...)
-		}
-		messages = append(messages, msg)
+	if strings.TrimSpace(req.CurrentMessage) != "" || len(req.Media) > 0 {
+		messages = append(messages, userPromptMessage(req.CurrentMessage, req.Media))
 	}
 
 	return messages
@@ -870,6 +1032,26 @@ The following skills are active for this request. Follow them when relevant.
 %s`, content)
 }
 
+func (cb *ContextBuilder) buildActiveSkillsPromptParts(skillNames []string) []PromptPart {
+	skillsText := cb.buildActiveSkillsContext(skillNames)
+	if strings.TrimSpace(skillsText) == "" {
+		return nil
+	}
+
+	return []PromptPart{
+		{
+			ID:      "capability.active_skills",
+			Layer:   PromptLayerCapability,
+			Slot:    PromptSlotActiveSkill,
+			Source:  PromptSource{ID: PromptSourceActiveSkills, Name: "skill:active"},
+			Title:   "active skills",
+			Content: skillsText,
+			Stable:  false,
+			Cache:   PromptCacheNone,
+		},
+	}
+}
+
 func (cb *ContextBuilder) ListSkillNames() []string {
 	if cb.skillsLoader == nil {
 		return nil

pkg/agent/hooks.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"reflect"
 	"sort"
 	"sync"
 	"time"
@@ -325,6 +326,7 @@ func (hm *HookManager) BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLM
 		switch decision.normalizedAction() {
 		case HookActionContinue, HookActionModify:
 			if next != nil {
+				next = hm.applyBeforeLLMControls(reg.Name, current, next)
 				current = next
 			}
 		case HookActionAbortTurn, HookActionHardAbort:
@@ -367,6 +369,84 @@ func (hm *HookManager) AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LL
 	return current, HookDecision{Action: HookActionContinue}
 }
 
+func (hm *HookManager) applyBeforeLLMControls(
+	hookName string,
+	current *LLMHookRequest,
+	next *LLMHookRequest,
+) *LLMHookRequest {
+	if next == nil || current == nil {
+		return next
+	}
+	if !llmHookSystemMessagesUnchanged(current.Messages, next.Messages) {
+		logger.WarnCF("hooks", "Hook attempted to modify system prompt; preserving original messages", map[string]any{
+			"hook": hookName,
+		})
+		next.Messages = cloneProviderMessages(current.Messages)
+	}
+	if !llmHookToolDefinitionsUnchanged(current.Tools, next.Tools) {
+		logger.WarnCF("hooks", "Hook attempted to modify tool definitions; preserving original tools", map[string]any{
+			"hook": hookName,
+		})
+		next.Tools = cloneToolDefinitions(current.Tools)
+	}
+	return next
+}
+
+func llmHookSystemMessagesUnchanged(before, after []providers.Message) bool {
+	beforeSystem := systemMessageFingerprints(before)
+	afterSystem := systemMessageFingerprints(after)
+	return reflect.DeepEqual(beforeSystem, afterSystem)
+}
+
+type systemMessageFingerprint struct {
+	Index   int
+	Message providers.Message
+}
+
+func systemMessageFingerprints(messages []providers.Message) []systemMessageFingerprint {
+	var fingerprints []systemMessageFingerprint
+	for i, msg := range messages {
+		if msg.Role != "system" {
+			continue
+		}
+		msg = providerVisibleMessage(msg)
+		fingerprints = append(fingerprints, systemMessageFingerprint{
+			Index:   i,
+			Message: cloneProviderMessages([]providers.Message{msg})[0],
+		})
+	}
+	return fingerprints
+}
+
+func llmHookToolDefinitionsUnchanged(before, after []providers.ToolDefinition) bool {
+	return reflect.DeepEqual(providerVisibleToolDefinitions(before), providerVisibleToolDefinitions(after))
+}
+
+func providerVisibleMessage(msg providers.Message) providers.Message {
+	msg.PromptLayer = ""
+	msg.PromptSlot = ""
+	msg.PromptSource = ""
+	if len(msg.SystemParts) > 0 {
+		msg.SystemParts = append([]providers.ContentBlock(nil), msg.SystemParts...)
+		for i := range msg.SystemParts {
+			msg.SystemParts[i].PromptLayer = ""
+			msg.SystemParts[i].PromptSlot = ""
+			msg.SystemParts[i].PromptSource = ""
+		}
+	}
+	return msg
+}
+
+func providerVisibleToolDefinitions(defs []providers.ToolDefinition) []providers.ToolDefinition {
+	cloned := cloneToolDefinitions(defs)
+	for i := range cloned {
+		cloned[i].PromptLayer = ""
+		cloned[i].PromptSlot = ""
+		cloned[i].PromptSource = ""
+	}
+	return cloned
+}
+
 func (hm *HookManager) BeforeTool(
 	ctx context.Context,
 	call *ToolCallHookRequest,
@@ -788,7 +868,7 @@ func cloneLLMResponse(resp *providers.LLMResponse) *providers.LLMResponse {
 
 func cloneStringAnyMap(src map[string]any) map[string]any {
 	if len(src) == 0 {
-		return nil
+		return map[string]any{}
 	}
 
 	cloned := make(map[string]any, len(src))

pkg/agent/hooks_test.go

@@ -2,6 +2,7 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"os"
 	"strings"
@@ -149,6 +150,268 @@ func (h *llmObserverHook) AfterLLM(
 	return next, HookDecision{Action: HookActionModify}, nil
 }
 
+type llmSystemRewriteHook struct{}
+
+func (h *llmSystemRewriteHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Model = "changed-model"
+	next.Messages[0].Content = "rewritten system"
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmSystemRewriteHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+type llmUserAppendHook struct{}
+
+func (h *llmUserAppendHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Messages = append(next.Messages, providers.Message{Role: "user", Content: "extra user context"})
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmUserAppendHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+type llmJSONRoundTripUserAppendHook struct{}
+
+type jsonRoundTripLLMHookRequest struct {
+	Model    string                     `json:"model"`
+	Messages []providers.Message        `json:"messages,omitempty"`
+	Tools    []providers.ToolDefinition `json:"tools,omitempty"`
+}
+
+func (h *llmJSONRoundTripUserAppendHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	payload := jsonRoundTripLLMHookRequest{
+		Model:    req.Model,
+		Messages: req.Messages,
+		Tools:    req.Tools,
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return nil, HookDecision{}, err
+	}
+	var decoded jsonRoundTripLLMHookRequest
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return nil, HookDecision{}, err
+	}
+	next := req.Clone()
+	next.Model = decoded.Model
+	next.Messages = decoded.Messages
+	next.Tools = decoded.Tools
+	next.Messages = append(next.Messages, providers.Message{Role: "user", Content: "json extra user context"})
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmJSONRoundTripUserAppendHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+type llmToolRewriteHook struct{}
+
+func (h *llmToolRewriteHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Model = "changed-model"
+	next.Tools[0].Function.Description = "rewritten tool"
+	next.Tools = append(next.Tools, providers.ToolDefinition{
+		Type: "function",
+		Function: providers.ToolFunctionDefinition{
+			Name:        "hook_tool",
+			Description: "hook tool",
+			Parameters:  map[string]any{"type": "object"},
+		},
+		PromptLayer:  string(PromptLayerCapability),
+		PromptSlot:   string(PromptSlotTooling),
+		PromptSource: "hook:test",
+	})
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmToolRewriteHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	return resp.Clone(), HookDecision{Action: HookActionContinue}, nil
+}
+
+func TestHookManager_BeforeLLMControlsSystemPromptMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("rewrite-system", &llmSystemRewriteHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "original-model",
+		Messages: []providers.Message{
+			{
+				Role:    "system",
+				Content: "original system",
+				SystemParts: []providers.ContentBlock{
+					{Type: "text", Text: "original system"},
+				},
+			},
+			{Role: "user", Content: "hello"},
+		},
+	}
+
+	got, decision := hm.BeforeLLM(context.Background(), req)
+	if decision.normalizedAction() != HookActionContinue {
+		t.Fatalf("decision = %v, want continue", decision)
+	}
+	if got.Model != "changed-model" {
+		t.Fatalf("model = %q, want changed-model", got.Model)
+	}
+	if got.Messages[0].Content != "original system" {
+		t.Fatalf("system content = %q, want original system", got.Messages[0].Content)
+	}
+	if got.Messages[1].Content != "hello" {
+		t.Fatalf("user content = %q, want hello", got.Messages[1].Content)
+	}
+}
+
+func TestHookManager_BeforeLLMAllowsNonSystemMessageMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("append-user", &llmUserAppendHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "model",
+		Messages: []providers.Message{
+			{Role: "system", Content: "system"},
+			{Role: "user", Content: "hello"},
+		},
+	}
+
+	got, _ := hm.BeforeLLM(context.Background(), req)
+	if len(got.Messages) != 3 {
+		t.Fatalf("messages len = %d, want 3", len(got.Messages))
+	}
+	if got.Messages[2].Role != "user" || got.Messages[2].Content != "extra user context" {
+		t.Fatalf("appended message = %#v, want extra user context", got.Messages[2])
+	}
+}
+
+func TestHookManager_BeforeLLMAllowsJSONRoundTripNonSystemMessageMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("json-append-user", &llmJSONRoundTripUserAppendHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "model",
+		Messages: []providers.Message{
+			{
+				Role:         "system",
+				Content:      "system",
+				PromptLayer:  string(PromptLayerKernel),
+				PromptSlot:   string(PromptSlotIdentity),
+				PromptSource: string(PromptSourceKernel),
+				SystemParts: []providers.ContentBlock{
+					{
+						Type:         "text",
+						Text:         "system",
+						CacheControl: &providers.CacheControl{Type: "ephemeral"},
+						PromptLayer:  string(PromptLayerKernel),
+						PromptSlot:   string(PromptSlotIdentity),
+						PromptSource: string(PromptSourceKernel),
+					},
+				},
+			},
+			{Role: "user", Content: "hello"},
+		},
+		Tools: []providers.ToolDefinition{
+			{
+				Type: "function",
+				Function: providers.ToolFunctionDefinition{
+					Name:        "mcp_github_create_issue",
+					Description: "create issue",
+					Parameters:  map[string]any{"type": "object"},
+				},
+				PromptLayer:  string(PromptLayerCapability),
+				PromptSlot:   string(PromptSlotMCP),
+				PromptSource: "mcp:github",
+			},
+		},
+	}
+
+	got, _ := hm.BeforeLLM(context.Background(), req)
+	if len(got.Messages) != 3 {
+		t.Fatalf("messages len = %d, want 3", len(got.Messages))
+	}
+	if got.Messages[2].Role != "user" || got.Messages[2].Content != "json extra user context" {
+		t.Fatalf("appended message = %#v, want json extra user context", got.Messages[2])
+	}
+}
+
+func TestHookManager_BeforeLLMControlsToolDefinitionMutation(t *testing.T) {
+	hm := NewHookManager(nil)
+	if err := hm.Mount(NamedHook("rewrite-tool", &llmToolRewriteHook{})); err != nil {
+		t.Fatalf("Mount() error = %v", err)
+	}
+
+	req := &LLMHookRequest{
+		Model: "original-model",
+		Messages: []providers.Message{
+			{Role: "system", Content: "system"},
+			{Role: "user", Content: "hello"},
+		},
+		Tools: []providers.ToolDefinition{
+			{
+				Type: "function",
+				Function: providers.ToolFunctionDefinition{
+					Name:        "mcp_github_create_issue",
+					Description: "create issue",
+					Parameters:  map[string]any{"type": "object"},
+				},
+				PromptLayer:  string(PromptLayerCapability),
+				PromptSlot:   string(PromptSlotMCP),
+				PromptSource: "mcp:github",
+			},
+		},
+	}
+
+	got, decision := hm.BeforeLLM(context.Background(), req)
+	if decision.normalizedAction() != HookActionContinue {
+		t.Fatalf("decision = %v, want continue", decision)
+	}
+	if got.Model != "changed-model" {
+		t.Fatalf("model = %q, want changed-model", got.Model)
+	}
+	if len(got.Tools) != 1 {
+		t.Fatalf("tools len = %d, want original 1", len(got.Tools))
+	}
+	if got.Tools[0].Function.Description != "create issue" {
+		t.Fatalf("tool description = %q, want original", got.Tools[0].Function.Description)
+	}
+	if got.Tools[0].PromptSource != "mcp:github" || got.Tools[0].PromptSlot != string(PromptSlotMCP) {
+		t.Fatalf("tool prompt metadata = %#v, want original mcp metadata", got.Tools[0])
+	}
+}
+
 func TestAgentLoop_Hooks_ObserverAndLLMInterceptor(t *testing.T) {
 	provider := &llmHookTestProvider{}
 	al, agent, cleanup := newHookTestLoop(t, provider)
@@ -1168,6 +1431,56 @@ func TestAgentLoop_HookRespond_SteeringSkipsRemaining(t *testing.T) {
 	}
 }
 
+func TestCloneStringAnyMap_EmptyMapReturnsNonNil(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   map[string]any
+		wantNil bool
+		wantLen int
+	}{
+		{
+			name:    "nil input returns empty map",
+			input:   nil,
+			wantNil: false,
+			wantLen: 0,
+		},
+		{
+			name:    "empty map returns empty map",
+			input:   map[string]any{},
+			wantNil: false,
+			wantLen: 0,
+		},
+		{
+			name:    "populated map is cloned",
+			input:   map[string]any{"key": "value"},
+			wantNil: false,
+			wantLen: 1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := cloneStringAnyMap(tt.input)
+			if result == nil {
+				t.Fatal("cloneStringAnyMap returned nil — MCP tool calls " +
+					"with no arguments would send null instead of {}")
+			}
+			if len(result) != tt.wantLen {
+				t.Fatalf("expected len %d, got %d", tt.wantLen, len(result))
+			}
+		})
+	}
+
+	t.Run("clone does not share underlying map", func(t *testing.T) {
+		src := map[string]any{"a": 1}
+		cloned := cloneStringAnyMap(src)
+		cloned["b"] = 2
+		if _, ok := src["b"]; ok {
+			t.Fatal("modifying clone should not affect source")
+		}
+	})
+}
+
 func filterEvents(events []Event, kind EventKind) []Event {
 	var result []Event
 	for _, evt := range events {

pkg/agent/interfaces/interfaces.go

@@ -44,4 +44,11 @@ type ChannelManager interface {
 
 	// SendPlaceholder sends a placeholder message (e.g., for audio transcription).
 	SendPlaceholder(ctx context.Context, channel, chatID string) bool
+
+	// DismissToolFeedback clears any tracked tool feedback animation for the
+	// given channel/chat. Call this when a turn ends without a final response
+	// (e.g., ResponseHandled tools) to avoid orphaned animation goroutines.
+	// outboundCtx carries topic/thread info needed for channels that use
+	// scoped tracker keys (e.g., Telegram forum topics); may be nil.
+	DismissToolFeedback(ctx context.Context, channel, chatID string, outboundCtx *bus.InboundContext)
 }

pkg/agent/pipeline_execute.go

@@ -80,14 +80,18 @@ toolLoop:
 						},
 					)
 
-					if shouldPublishToolFeedback(al.cfg, ts) {
+					if shouldPublishToolFeedback(al.cfg, ts) && ts.channel != "pico" {
+						toolFeedbackMaxLen := al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength()
 						toolFeedbackExplanation := toolFeedbackExplanationForToolCall(
 							exec.response,
 							tc,
 							messages,
-							al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
 						)
-						feedbackMsg := utils.FormatToolFeedbackMessage(toolName, toolFeedbackExplanation)
+						feedbackMsg := utils.FormatToolFeedbackMessage(
+							toolName,
+							toolFeedbackExplanation,
+							toolFeedbackArgsPreview(toolArgs, toolFeedbackMaxLen),
+						)
 						fbCtx, fbCancel := context.WithTimeout(turnCtx, 3*time.Second)
 						_ = al.bus.PublishOutbound(fbCtx, outboundMessageForTurnWithKind(ts, feedbackMsg, messageKindToolFeedback))
 						fbCancel()
@@ -260,7 +264,7 @@ toolLoop:
 						case result, ok := <-ts.pendingResults:
 							if ok && result != nil && result.ForLLM != "" {
 								content := al.cfg.FilterSensitiveData(result.ForLLM)
-								msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", content)}
+								msg := subTurnResultPromptMessage(content)
 								messages = append(messages, msg)
 								ts.agent.Sessions.AddFullMessage(ts.sessionKey, msg)
 							}
@@ -357,14 +361,18 @@ toolLoop:
 			},
 		)
 
-		if shouldPublishToolFeedback(al.cfg, ts) {
+		if shouldPublishToolFeedback(al.cfg, ts) && ts.channel != "pico" {
+			toolFeedbackMaxLen := al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength()
 			toolFeedbackExplanation := toolFeedbackExplanationForToolCall(
 				exec.response,
 				tc,
 				messages,
-				al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
 			)
-			feedbackMsg := utils.FormatToolFeedbackMessage(toolName, toolFeedbackExplanation)
+			feedbackMsg := utils.FormatToolFeedbackMessage(
+				toolName,
+				toolFeedbackExplanation,
+				toolFeedbackArgsPreview(toolArgs, toolFeedbackMaxLen),
+			)
 			fbCtx, fbCancel := context.WithTimeout(turnCtx, 3*time.Second)
 			_ = al.bus.PublishOutbound(fbCtx, outboundMessageForTurnWithKind(ts, feedbackMsg, messageKindToolFeedback))
 			fbCancel()
@@ -631,7 +639,7 @@ toolLoop:
 			case result, ok := <-ts.pendingResults:
 				if ok && result != nil && result.ForLLM != "" {
 					content := al.cfg.FilterSensitiveData(result.ForLLM)
-					msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", content)}
+					msg := subTurnResultPromptMessage(content)
 					messages = append(messages, msg)
 					ts.agent.Sessions.AddFullMessage(ts.sessionKey, msg)
 				}
@@ -696,6 +704,9 @@ toolLoop:
 		}
 		ts.setPhase(TurnPhaseCompleted)
 		ts.setFinalContent("")
+		if al.channelManager != nil && ts.channel != "" {
+			al.channelManager.DismissToolFeedback(ctx, ts.channel, ts.chatID, ts.opts.InboundContext)
+		}
 		logger.InfoCF("agent", "Tool output satisfied delivery; ending turn without follow-up LLM",
 			map[string]any{
 				"agent_id":   ts.agent.ID,

pkg/agent/pipeline_finalize.go

@@ -40,8 +40,12 @@ func (p *Pipeline) Finalize(
 	ts.setPhase(TurnPhaseFinalizing)
 	ts.setFinalContent(finalContent)
 	if !ts.opts.NoHistory {
-		finalMsg := providers.Message{Role: "assistant", Content: finalContent}
-		ts.agent.Sessions.AddMessage(ts.sessionKey, finalMsg.Role, finalMsg.Content)
+		finalMsg := providers.Message{
+			Role:             "assistant",
+			Content:          finalContent,
+			ReasoningContent: responseReasoningContent(exec.response),
+		}
+		ts.agent.Sessions.AddFullMessage(ts.sessionKey, finalMsg)
 		ts.recordPersistedMessage(finalMsg)
 		ts.ingestMessage(turnCtx, al, finalMsg)
 		if err := ts.agent.Sessions.Save(ts.sessionKey); err != nil {

pkg/agent/pipeline_llm.go

@@ -10,7 +10,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/constants"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
@@ -319,10 +318,8 @@ func (p *Pipeline) CallLLM(
 				exec.history = asmResp.History
 				exec.summary = asmResp.Summary
 			}
-			exec.messages = ts.agent.ContextBuilder.BuildMessages(
-				exec.history, exec.summary, "",
-				nil, ts.channel, ts.chatID, ts.opts.Dispatch.SenderID(), ts.opts.SenderDisplayName,
-				activeSkillNames(ts.agent, ts.opts)...,
+			exec.messages = ts.agent.ContextBuilder.BuildMessagesFromPrompt(
+				promptBuildRequestForTurn(ts, exec.history, exec.summary, "", nil),
 			)
 			exec.callMessages = exec.messages
 			if exec.gracefulTerminal {
@@ -384,11 +381,12 @@ func (p *Pipeline) CallLLM(
 		}
 	}
 
-	reasoningContent := exec.response.Reasoning
-	if reasoningContent == "" {
-		reasoningContent = exec.response.ReasoningContent
-	}
-	if ts.channel == "pico" {
+	reasoningContent := responseReasoningContent(exec.response)
+	shouldPublishPicoToolCallInterim := ts.channel == "pico" && len(exec.response.ToolCalls) > 0
+	if shouldPublishPicoToolCallInterim {
+		// Pico tool-call turns publish their reasoning/content/tool summary as a
+		// structured sequence after the tool-call payload is normalized below.
+	} else if ts.channel == "pico" {
 		go al.publishPicoReasoning(turnCtx, reasoningContent, ts.chatID)
 	} else {
 		go al.handleReasoning(
@@ -424,30 +422,6 @@ func (p *Pipeline) CallLLM(
 	}
 	logger.DebugCF("agent", "LLM response", llmResponseFields)
 
-	if al.bus != nil &&
-		ts.channel == "pico" &&
-		len(exec.response.ToolCalls) > 0 &&
-		ts.opts.AllowInterimPicoPublish &&
-		!shouldPublishToolFeedback(al.cfg, ts) {
-		if strings.TrimSpace(exec.response.Content) != "" {
-			outCtx, outCancel := context.WithTimeout(turnCtx, 3*time.Second)
-			publishErr := al.bus.PublishOutbound(outCtx, bus.OutboundMessage{
-				Channel: ts.channel,
-				ChatID:  ts.chatID,
-				Content: exec.response.Content,
-			})
-			outCancel()
-			if publishErr != nil {
-				logger.WarnCF("agent", "Failed to publish pico interim tool-call content", map[string]any{
-					"error":     publishErr.Error(),
-					"channel":   ts.channel,
-					"chat_id":   ts.chatID,
-					"iteration": iteration,
-				})
-			}
-		}
-	}
-
 	// No-tool-call path: steering check and direct response
 	if len(exec.response.ToolCalls) == 0 || exec.gracefulTerminal {
 		responseContent := exec.response.Content
@@ -496,7 +470,7 @@ func (p *Pipeline) CallLLM(
 	assistantMsg := providers.Message{
 		Role:             "assistant",
 		Content:          exec.response.Content,
-		ReasoningContent: exec.response.ReasoningContent,
+		ReasoningContent: reasoningContent,
 	}
 	for _, tc := range exec.normalizedToolCalls {
 		argumentsJSON, _ := json.Marshal(tc.Arguments)
@@ -504,7 +478,6 @@ func (p *Pipeline) CallLLM(
 			exec.response,
 			tc,
 			exec.messages,
-			al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
 		)
 		extraContent := tc.ExtraContent
 		if strings.TrimSpace(toolFeedbackExplanation) != "" {
@@ -536,6 +509,15 @@ func (p *Pipeline) CallLLM(
 		ts.recordPersistedMessage(assistantMsg)
 		ts.ingestMessage(turnCtx, al, assistantMsg)
 	}
+	if shouldPublishPicoToolCallInterim {
+		al.publishPicoToolCallInterim(
+			turnCtx,
+			ts,
+			reasoningContent,
+			exec.response.Content,
+			assistantMsg.ToolCalls,
+		)
+	}
 
 	return ControlToolLoop, nil
 }

pkg/agent/pipeline_setup.go

@@ -31,16 +31,8 @@ func (p *Pipeline) SetupTurn(ctx context.Context, ts *turnState) (*turnExecution
 	}
 	ts.captureRestorePoint(history, summary)
 
-	messages := ts.agent.ContextBuilder.BuildMessages(
-		history,
-		summary,
-		ts.userMessage,
-		ts.media,
-		ts.channel,
-		ts.chatID,
-		ts.opts.Dispatch.SenderID(),
-		ts.opts.SenderDisplayName,
-		activeSkillNames(ts.agent, ts.opts)...,
+	messages := ts.agent.ContextBuilder.BuildMessagesFromPrompt(
+		promptBuildRequestForTurn(ts, history, summary, ts.userMessage, ts.media),
 	)
 
 	messages = resolveMediaRefs(messages, p.MediaStore, maxMediaSize)
@@ -69,22 +61,15 @@ func (p *Pipeline) SetupTurn(ctx context.Context, ts *turnState) (*turnExecution
 				history = resp.History
 				summary = resp.Summary
 			}
-			messages = ts.agent.ContextBuilder.BuildMessages(
-				history, summary, ts.userMessage,
-				ts.media, ts.channel, ts.chatID,
-				ts.opts.Dispatch.SenderID(), ts.opts.SenderDisplayName,
-				activeSkillNames(ts.agent, ts.opts)...,
+			messages = ts.agent.ContextBuilder.BuildMessagesFromPrompt(
+				promptBuildRequestForTurn(ts, history, summary, ts.userMessage, ts.media),
 			)
 			messages = resolveMediaRefs(messages, p.MediaStore, maxMediaSize)
 		}
 	}
 
 	if !ts.opts.NoHistory && (strings.TrimSpace(ts.userMessage) != "" || len(ts.media) > 0) {
-		rootMsg := providers.Message{
-			Role:    "user",
-			Content: ts.userMessage,
-			Media:   append([]string(nil), ts.media...),
-		}
+		rootMsg := userPromptMessage(ts.userMessage, ts.media)
 		if len(rootMsg.Media) > 0 {
 			ts.agent.Sessions.AddFullMessage(ts.sessionKey, rootMsg)
 		} else {

pkg/agent/prompt.go

@@ -0,0 +1,496 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"slices"
+	"strings"
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+type PromptLayer string
+
+const (
+	PromptLayerKernel      PromptLayer = "kernel"
+	PromptLayerInstruction PromptLayer = "instruction"
+	PromptLayerCapability  PromptLayer = "capability"
+	PromptLayerContext     PromptLayer = "context"
+	PromptLayerTurn        PromptLayer = "turn"
+)
+
+type PromptSlot string
+
+const (
+	PromptSlotIdentity     PromptSlot = "identity"
+	PromptSlotHierarchy    PromptSlot = "hierarchy"
+	PromptSlotWorkspace    PromptSlot = "workspace"
+	PromptSlotTooling      PromptSlot = "tooling"
+	PromptSlotMCP          PromptSlot = "mcp"
+	PromptSlotSkillCatalog PromptSlot = "skill_catalog"
+	PromptSlotActiveSkill  PromptSlot = "active_skill"
+	PromptSlotMemory       PromptSlot = "memory"
+	PromptSlotRuntime      PromptSlot = "runtime"
+	PromptSlotSummary      PromptSlot = "summary"
+	PromptSlotMessage      PromptSlot = "message"
+	PromptSlotSteering     PromptSlot = "steering"
+	PromptSlotSubTurn      PromptSlot = "subturn"
+	PromptSlotInterrupt    PromptSlot = "interrupt"
+	PromptSlotOutput       PromptSlot = "output"
+)
+
+type PromptSourceID string
+
+const (
+	PromptSourceKernel         PromptSourceID = "runtime.kernel"
+	PromptSourceHierarchy      PromptSourceID = "runtime.hierarchy"
+	PromptSourceWorkspace      PromptSourceID = "workspace.definition"
+	PromptSourceRuntime        PromptSourceID = "runtime.context"
+	PromptSourceSummary        PromptSourceID = "context.summary"
+	PromptSourceMemory         PromptSourceID = "memory:workspace"
+	PromptSourceSkillCatalog   PromptSourceID = "skill:index"
+	PromptSourceActiveSkills   PromptSourceID = "skill:active"
+	PromptSourceToolRegistry   PromptSourceID = "tool_registry:native"
+	PromptSourceToolDiscovery  PromptSourceID = "tool_registry:discovery"
+	PromptSourceOutputPolicy   PromptSourceID = "runtime.output"
+	PromptSourceSubTurnProfile PromptSourceID = "subturn.profile"
+	PromptSourceUserMessage    PromptSourceID = "turn:user_message"
+	PromptSourceSteering       PromptSourceID = "turn:steering"
+	PromptSourceSubTurnResult  PromptSourceID = "turn:subturn_result"
+	PromptSourceInterrupt      PromptSourceID = "turn:interrupt"
+)
+
+type PromptCachePolicy string
+
+const (
+	PromptCacheDefault   PromptCachePolicy = ""
+	PromptCacheEphemeral PromptCachePolicy = "ephemeral"
+	PromptCacheNone      PromptCachePolicy = "none"
+)
+
+type PromptPlacement struct {
+	Layer PromptLayer
+	Slot  PromptSlot
+}
+
+type PromptSourceDescriptor struct {
+	ID              PromptSourceID
+	Owner           string
+	Description     string
+	Allowed         []PromptPlacement
+	StableByDefault bool
+}
+
+type PromptSource struct {
+	ID   PromptSourceID
+	Name string
+	Path string
+}
+
+type PromptPart struct {
+	ID      string
+	Layer   PromptLayer
+	Slot    PromptSlot
+	Source  PromptSource
+	Title   string
+	Content string
+	Stable  bool
+	Cache   PromptCachePolicy
+}
+
+type PromptBuildRequest struct {
+	History []providers.Message
+	Summary string
+
+	CurrentMessage string
+	Media          []string
+
+	Channel           string
+	ChatID            string
+	SenderID          string
+	SenderDisplayName string
+
+	ActiveSkills []string
+	Overlays     []PromptPart
+}
+
+type PromptContributor interface {
+	PromptSource() PromptSourceDescriptor
+	ContributePrompt(ctx context.Context, req PromptBuildRequest) ([]PromptPart, error)
+}
+
+type PromptRegistry struct {
+	mu           sync.RWMutex
+	sources      map[PromptSourceID]PromptSourceDescriptor
+	contributors []PromptContributor
+	warned       map[PromptSourceID]struct{}
+}
+
+func NewPromptRegistry() *PromptRegistry {
+	r := &PromptRegistry{
+		sources: make(map[PromptSourceID]PromptSourceDescriptor),
+		warned:  make(map[PromptSourceID]struct{}),
+	}
+	for _, desc := range builtinPromptSources() {
+		if err := r.RegisterSource(desc); err != nil {
+			logger.WarnCF("agent", "Failed to register builtin prompt source", map[string]any{
+				"source": desc.ID,
+				"error":  err.Error(),
+			})
+		}
+	}
+	return r
+}
+
+func builtinPromptSources() []PromptSourceDescriptor {
+	return []PromptSourceDescriptor{
+		{
+			ID:              PromptSourceKernel,
+			Owner:           "agent",
+			Description:     "Core picoclaw identity and hard rules",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerKernel, Slot: PromptSlotIdentity}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceHierarchy,
+			Owner:           "agent",
+			Description:     "Prompt hierarchy rules",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerKernel, Slot: PromptSlotHierarchy}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceWorkspace,
+			Owner:           "workspace",
+			Description:     "Workspace and agent definition files",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerInstruction, Slot: PromptSlotWorkspace}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceToolDiscovery,
+			Owner:           "tools",
+			Description:     "Tool discovery instructions",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotTooling}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceToolRegistry,
+			Owner:           "tools",
+			Description:     "Native provider tool definitions",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotTooling}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceSkillCatalog,
+			Owner:           "skills",
+			Description:     "Installed skill catalog",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotSkillCatalog}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceActiveSkills,
+			Owner:           "skills",
+			Description:     "Active skill instructions for the current request",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotActiveSkill}},
+			StableByDefault: false,
+		},
+		{
+			ID:              PromptSourceMemory,
+			Owner:           "memory",
+			Description:     "Workspace memory context",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerContext, Slot: PromptSlotMemory}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceRuntime,
+			Owner:           "agent",
+			Description:     "Per-request runtime context",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerContext, Slot: PromptSlotRuntime}},
+			StableByDefault: false,
+		},
+		{
+			ID:              PromptSourceSummary,
+			Owner:           "context_manager",
+			Description:     "Conversation summary context",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerContext, Slot: PromptSlotSummary}},
+			StableByDefault: false,
+		},
+		{
+			ID:              PromptSourceOutputPolicy,
+			Owner:           "agent",
+			Description:     "Output formatting policy",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerContext, Slot: PromptSlotOutput}},
+			StableByDefault: true,
+		},
+		{
+			ID:              PromptSourceSubTurnProfile,
+			Owner:           "subturn",
+			Description:     "Child agent profile instructions",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerInstruction, Slot: PromptSlotWorkspace}},
+			StableByDefault: false,
+		},
+		{
+			ID:              PromptSourceUserMessage,
+			Owner:           "turn",
+			Description:     "Current user message for this turn",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerTurn, Slot: PromptSlotMessage}},
+			StableByDefault: false,
+		},
+		{
+			ID:              PromptSourceSteering,
+			Owner:           "turn",
+			Description:     "Steering message injected into a running turn",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerTurn, Slot: PromptSlotSteering}},
+			StableByDefault: false,
+		},
+		{
+			ID:              PromptSourceSubTurnResult,
+			Owner:           "turn",
+			Description:     "SubTurn result injected into a parent turn",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerTurn, Slot: PromptSlotSubTurn}},
+			StableByDefault: false,
+		},
+		{
+			ID:              PromptSourceInterrupt,
+			Owner:           "turn",
+			Description:     "Graceful interrupt hint injected into the terminal LLM call",
+			Allowed:         []PromptPlacement{{Layer: PromptLayerTurn, Slot: PromptSlotInterrupt}},
+			StableByDefault: false,
+		},
+	}
+}
+
+func (r *PromptRegistry) RegisterSource(desc PromptSourceDescriptor) error {
+	if r == nil {
+		return fmt.Errorf("prompt registry is nil")
+	}
+	desc.ID = PromptSourceID(strings.TrimSpace(string(desc.ID)))
+	if desc.ID == "" {
+		return fmt.Errorf("prompt source id is required")
+	}
+	if len(desc.Allowed) == 0 {
+		return fmt.Errorf("prompt source %q must declare at least one placement", desc.ID)
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.sources[desc.ID] = clonePromptSourceDescriptor(desc)
+	return nil
+}
+
+func (r *PromptRegistry) RegisterContributor(contributor PromptContributor) error {
+	if r == nil {
+		return fmt.Errorf("prompt registry is nil")
+	}
+	if contributor == nil {
+		return fmt.Errorf("prompt contributor is nil")
+	}
+	desc := contributor.PromptSource()
+	desc.ID = PromptSourceID(strings.TrimSpace(string(desc.ID)))
+	if err := r.RegisterSource(desc); err != nil {
+		return err
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.contributors = slices.DeleteFunc(r.contributors, func(existing PromptContributor) bool {
+		return PromptSourceID(strings.TrimSpace(string(existing.PromptSource().ID))) == desc.ID
+	})
+	r.contributors = append(r.contributors, contributor)
+	return nil
+}
+
+func (r *PromptRegistry) Collect(ctx context.Context, req PromptBuildRequest) ([]PromptPart, error) {
+	if r == nil {
+		return nil, nil
+	}
+
+	r.mu.RLock()
+	contributors := append([]PromptContributor(nil), r.contributors...)
+	r.mu.RUnlock()
+
+	var parts []PromptPart
+	for _, contributor := range contributors {
+		contributed, err := contributor.ContributePrompt(ctx, req)
+		if err != nil {
+			return nil, err
+		}
+		for _, part := range contributed {
+			if err := r.ValidatePart(part); err != nil {
+				return nil, err
+			}
+			parts = append(parts, part)
+		}
+	}
+	return parts, nil
+}
+
+func (r *PromptRegistry) ValidatePart(part PromptPart) error {
+	if r == nil {
+		return nil
+	}
+	sourceID := PromptSourceID(strings.TrimSpace(string(part.Source.ID)))
+	if sourceID == "" {
+		return fmt.Errorf("prompt part %q has empty source id", part.ID)
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	desc, ok := r.sources[sourceID]
+	if !ok {
+		if _, warned := r.warned[sourceID]; !warned {
+			r.warned[sourceID] = struct{}{}
+			logger.WarnCF("agent", "Unregistered prompt source allowed in compatibility mode", map[string]any{
+				"source": sourceID,
+				"layer":  part.Layer,
+				"slot":   part.Slot,
+				"part":   part.ID,
+			})
+		}
+		return nil
+	}
+	if promptPlacementAllowed(desc.Allowed, PromptPlacement{Layer: part.Layer, Slot: part.Slot}) {
+		return nil
+	}
+	return fmt.Errorf("prompt source %q cannot write to %s/%s", sourceID, part.Layer, part.Slot)
+}
+
+func promptPlacementAllowed(allowed []PromptPlacement, placement PromptPlacement) bool {
+	return slices.ContainsFunc(allowed, func(candidate PromptPlacement) bool {
+		return candidate.Layer == placement.Layer && candidate.Slot == placement.Slot
+	})
+}
+
+func clonePromptSourceDescriptor(desc PromptSourceDescriptor) PromptSourceDescriptor {
+	desc.Allowed = append([]PromptPlacement(nil), desc.Allowed...)
+	return desc
+}
+
+type PromptStack struct {
+	registry *PromptRegistry
+	parts    []PromptPart
+	sealed   bool
+}
+
+func NewPromptStack(registry *PromptRegistry) *PromptStack {
+	return &PromptStack{registry: registry}
+}
+
+func (s *PromptStack) Add(part PromptPart) error {
+	if s == nil {
+		return fmt.Errorf("prompt stack is nil")
+	}
+	if s.sealed {
+		return fmt.Errorf("prompt stack is sealed")
+	}
+	if strings.TrimSpace(part.Content) == "" {
+		return nil
+	}
+	if strings.TrimSpace(part.ID) == "" {
+		return fmt.Errorf("prompt part id is required")
+	}
+	if s.registry != nil {
+		if err := s.registry.ValidatePart(part); err != nil {
+			return err
+		}
+	}
+	s.parts = append(s.parts, part)
+	return nil
+}
+
+func (s *PromptStack) Seal() {
+	if s != nil {
+		s.sealed = true
+	}
+}
+
+func (s *PromptStack) Parts() []PromptPart {
+	if s == nil || len(s.parts) == 0 {
+		return nil
+	}
+	return append([]PromptPart(nil), s.parts...)
+}
+
+func renderPromptPartsLegacy(parts []PromptPart) string {
+	textParts := make([]string, 0, len(parts))
+	for _, part := range sortPromptParts(parts) {
+		if strings.TrimSpace(part.Content) == "" {
+			continue
+		}
+		textParts = append(textParts, part.Content)
+	}
+	return strings.Join(textParts, "\n\n---\n\n")
+}
+
+func sortPromptParts(parts []PromptPart) []PromptPart {
+	sorted := append([]PromptPart(nil), parts...)
+	slices.SortStableFunc(sorted, func(a, b PromptPart) int {
+		if d := layerPriority(b.Layer) - layerPriority(a.Layer); d != 0 {
+			return d
+		}
+		if d := slotPriority(b.Slot) - slotPriority(a.Slot); d != 0 {
+			return d
+		}
+		if a.Source.ID != b.Source.ID {
+			return strings.Compare(string(a.Source.ID), string(b.Source.ID))
+		}
+		return strings.Compare(a.ID, b.ID)
+	})
+	return sorted
+}
+
+func layerPriority(layer PromptLayer) int {
+	switch layer {
+	case PromptLayerKernel:
+		return 100
+	case PromptLayerInstruction:
+		return 80
+	case PromptLayerCapability:
+		return 60
+	case PromptLayerContext:
+		return 40
+	case PromptLayerTurn:
+		return 20
+	default:
+		return 0
+	}
+}
+
+func slotPriority(slot PromptSlot) int {
+	switch slot {
+	case PromptSlotIdentity:
+		return 1000
+	case PromptSlotHierarchy:
+		return 990
+	case PromptSlotWorkspace:
+		return 900
+	case PromptSlotTooling:
+		return 800
+	case PromptSlotMCP:
+		return 790
+	case PromptSlotSkillCatalog:
+		return 780
+	case PromptSlotActiveSkill:
+		return 770
+	case PromptSlotMemory:
+		return 700
+	case PromptSlotOutput:
+		return 695
+	case PromptSlotRuntime:
+		return 690
+	case PromptSlotSummary:
+		return 680
+	case PromptSlotMessage:
+		return 600
+	case PromptSlotSteering:
+		return 590
+	case PromptSlotSubTurn:
+		return 580
+	case PromptSlotInterrupt:
+		return 570
+	default:
+		return 0
+	}
+}

pkg/agent/prompt_contributors.go

@@ -0,0 +1,139 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+type toolDiscoveryPromptContributor struct {
+	useBM25  bool
+	useRegex bool
+}
+
+func (c toolDiscoveryPromptContributor) PromptSource() PromptSourceDescriptor {
+	return PromptSourceDescriptor{
+		ID:              PromptSourceToolDiscovery,
+		Owner:           "tools",
+		Description:     "Tool discovery instructions",
+		Allowed:         []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotTooling}},
+		StableByDefault: true,
+	}
+}
+
+func (c toolDiscoveryPromptContributor) ContributePrompt(
+	_ context.Context,
+	_ PromptBuildRequest,
+) ([]PromptPart, error) {
+	content := formatToolDiscoveryRule(c.useBM25, c.useRegex)
+	if strings.TrimSpace(content) == "" {
+		return nil, nil
+	}
+
+	return []PromptPart{
+		{
+			ID:      "capability.tool_discovery",
+			Layer:   PromptLayerCapability,
+			Slot:    PromptSlotTooling,
+			Source:  PromptSource{ID: PromptSourceToolDiscovery, Name: "tool_registry:discovery"},
+			Title:   "tool discovery",
+			Content: content,
+			Stable:  true,
+			Cache:   PromptCacheEphemeral,
+		},
+	}, nil
+}
+
+type mcpServerPromptContributor struct {
+	serverName string
+	toolCount  int
+	deferred   bool
+}
+
+func (c mcpServerPromptContributor) PromptSource() PromptSourceDescriptor {
+	return PromptSourceDescriptor{
+		ID:              mcpPromptSourceID(c.serverName),
+		Owner:           "mcp",
+		Description:     fmt.Sprintf("MCP server %q capability prompt", c.serverName),
+		Allowed:         []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotMCP}},
+		StableByDefault: true,
+	}
+}
+
+func (c mcpServerPromptContributor) ContributePrompt(
+	_ context.Context,
+	_ PromptBuildRequest,
+) ([]PromptPart, error) {
+	serverName := strings.TrimSpace(c.serverName)
+	if serverName == "" || c.toolCount <= 0 {
+		return nil, nil
+	}
+
+	availability := "available as native tools"
+	if c.deferred {
+		availability = "hidden behind tool discovery until unlocked"
+	}
+
+	return []PromptPart{
+		{
+			ID:     "capability.mcp." + promptSourceComponent(serverName),
+			Layer:  PromptLayerCapability,
+			Slot:   PromptSlotMCP,
+			Source: PromptSource{ID: mcpPromptSourceID(serverName), Name: "mcp:" + serverName},
+			Title:  "MCP server capability",
+			Content: fmt.Sprintf(
+				"MCP server `%s` is connected. It contributes %d tool(s), currently %s.",
+				serverName,
+				c.toolCount,
+				availability,
+			),
+			Stable: true,
+			Cache:  PromptCacheEphemeral,
+		},
+	}, nil
+}
+
+func mcpPromptSourceID(serverName string) PromptSourceID {
+	return PromptSourceID("mcp:" + promptSourceComponent(serverName))
+}
+
+func promptSourceComponent(value string) string {
+	const maxLen = 64
+
+	value = strings.ToLower(strings.TrimSpace(value))
+	if value == "" {
+		return "unnamed"
+	}
+
+	var b strings.Builder
+	lastWasSep := false
+	for _, r := range value {
+		switch {
+		case r >= 'a' && r <= 'z':
+			b.WriteRune(r)
+			lastWasSep = false
+		case r >= '0' && r <= '9':
+			b.WriteRune(r)
+			lastWasSep = false
+		case r == '-' || r == '_':
+			if !lastWasSep && b.Len() > 0 {
+				b.WriteRune(r)
+				lastWasSep = true
+			}
+		default:
+			if !lastWasSep && b.Len() > 0 {
+				b.WriteRune('_')
+				lastWasSep = true
+			}
+		}
+	}
+
+	result := strings.Trim(b.String(), "_")
+	if result == "" {
+		return "unnamed"
+	}
+	if len(result) > maxLen {
+		return result[:maxLen]
+	}
+	return result
+}

pkg/agent/prompt_test.go

@@ -0,0 +1,275 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestPromptRegistry_RejectsRegisteredSourceWrongPlacement(t *testing.T) {
+	registry := NewPromptRegistry()
+	if err := registry.RegisterSource(PromptSourceDescriptor{
+		ID:      "test:source",
+		Owner:   "test",
+		Allowed: []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotTooling}},
+	}); err != nil {
+		t.Fatalf("RegisterSource() error = %v", err)
+	}
+
+	err := registry.ValidatePart(PromptPart{
+		ID:      "wrong.placement",
+		Layer:   PromptLayerContext,
+		Slot:    PromptSlotRuntime,
+		Source:  PromptSource{ID: "test:source"},
+		Content: "runtime text",
+	})
+	if err == nil {
+		t.Fatal("ValidatePart() error = nil, want placement error")
+	}
+}
+
+func TestPromptRegistry_AllowsUnregisteredSourceInCompatibilityMode(t *testing.T) {
+	registry := NewPromptRegistry()
+
+	err := registry.ValidatePart(PromptPart{
+		ID:      "unregistered.part",
+		Layer:   PromptLayerCapability,
+		Slot:    PromptSlotMCP,
+		Source:  PromptSource{ID: "mcp:dynamic-server"},
+		Content: "dynamic MCP prompt",
+	})
+	if err != nil {
+		t.Fatalf("ValidatePart() error = %v, want nil for unregistered source", err)
+	}
+}
+
+func TestRenderPromptPartsLegacy_UsesLayerAndSlotOrder(t *testing.T) {
+	parts := []PromptPart{
+		{
+			ID:      "context.runtime",
+			Layer:   PromptLayerContext,
+			Slot:    PromptSlotRuntime,
+			Source:  PromptSource{ID: PromptSourceRuntime},
+			Content: "runtime",
+		},
+		{
+			ID:      "kernel.identity",
+			Layer:   PromptLayerKernel,
+			Slot:    PromptSlotIdentity,
+			Source:  PromptSource{ID: PromptSourceKernel},
+			Content: "kernel",
+		},
+		{
+			ID:      "capability.skill",
+			Layer:   PromptLayerCapability,
+			Slot:    PromptSlotActiveSkill,
+			Source:  PromptSource{ID: "skill:test"},
+			Content: "skill",
+		},
+		{
+			ID:      "instruction.workspace",
+			Layer:   PromptLayerInstruction,
+			Slot:    PromptSlotWorkspace,
+			Source:  PromptSource{ID: PromptSourceWorkspace},
+			Content: "workspace",
+		},
+	}
+
+	got := renderPromptPartsLegacy(parts)
+	want := strings.Join([]string{"kernel", "workspace", "skill", "runtime"}, "\n\n---\n\n")
+	if got != want {
+		t.Fatalf("renderPromptPartsLegacy() = %q, want %q", got, want)
+	}
+}
+
+func TestBuildMessagesFromPrompt_IncludesSystemPromptOverlay(t *testing.T) {
+	t.Setenv("PICOCLAW_BUILTIN_SKILLS", t.TempDir())
+	cb := NewContextBuilder(t.TempDir())
+
+	messages := cb.BuildMessagesFromPrompt(PromptBuildRequest{
+		CurrentMessage: "do child task",
+		Overlays: promptOverlaysForOptions(processOptions{
+			SystemPromptOverride: "Use child-only system instructions.",
+		}),
+	})
+
+	if len(messages) < 2 {
+		t.Fatalf("messages len = %d, want at least 2", len(messages))
+	}
+	if messages[0].Role != "system" {
+		t.Fatalf("messages[0].Role = %q, want system", messages[0].Role)
+	}
+	if !strings.Contains(messages[0].Content, "Use child-only system instructions.") {
+		t.Fatalf("system prompt missing overlay: %q", messages[0].Content)
+	}
+	if messages[1].Role != "user" || messages[1].Content != "do child task" {
+		t.Fatalf("messages[1] = %#v, want user task", messages[1])
+	}
+}
+
+func TestBuildMessagesFromPrompt_AttachesInternalPromptMetadata(t *testing.T) {
+	t.Setenv("PICOCLAW_BUILTIN_SKILLS", t.TempDir())
+	cb := NewContextBuilder(t.TempDir())
+
+	messages := cb.BuildMessagesFromPrompt(PromptBuildRequest{
+		CurrentMessage: "hello",
+		Summary:        "prior context",
+	})
+	if len(messages) != 2 {
+		t.Fatalf("messages len = %d, want 2", len(messages))
+	}
+
+	system := messages[0]
+	if len(system.SystemParts) < 3 {
+		t.Fatalf("system parts len = %d, want at least 3", len(system.SystemParts))
+	}
+	if system.SystemParts[0].PromptLayer != string(PromptLayerKernel) ||
+		system.SystemParts[0].PromptSlot != string(PromptSlotIdentity) ||
+		system.SystemParts[0].PromptSource != string(PromptSourceKernel) {
+		t.Fatalf("static system metadata = %#v, want kernel identity", system.SystemParts[0])
+	}
+
+	var hasRuntime, hasSummary bool
+	for _, part := range system.SystemParts {
+		switch part.PromptSource {
+		case string(PromptSourceRuntime):
+			hasRuntime = true
+			if part.CacheControl != nil {
+				t.Fatalf("runtime cache control = %#v, want nil", part.CacheControl)
+			}
+		case string(PromptSourceSummary):
+			hasSummary = true
+			if part.CacheControl != nil {
+				t.Fatalf("summary cache control = %#v, want nil", part.CacheControl)
+			}
+		}
+	}
+	if !hasRuntime {
+		t.Fatal("system parts missing runtime prompt metadata")
+	}
+	if !hasSummary {
+		t.Fatal("system parts missing summary prompt metadata")
+	}
+
+	user := messages[1]
+	if user.PromptLayer != string(PromptLayerTurn) ||
+		user.PromptSlot != string(PromptSlotMessage) ||
+		user.PromptSource != string(PromptSourceUserMessage) {
+		t.Fatalf("user message metadata = %#v, want turn message", user)
+	}
+
+	data, err := json.Marshal(messages)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	if strings.Contains(string(data), "PromptSource") ||
+		strings.Contains(string(data), "PromptLayer") ||
+		strings.Contains(string(data), "PromptSlot") {
+		t.Fatalf("internal prompt metadata leaked into JSON: %s", data)
+	}
+}
+
+func TestContextBuilder_CollectsToolDiscoveryContributor(t *testing.T) {
+	t.Setenv("PICOCLAW_BUILTIN_SKILLS", t.TempDir())
+	cb := NewContextBuilder(t.TempDir()).WithToolDiscovery(true, false)
+
+	messages := cb.BuildMessagesFromPrompt(PromptBuildRequest{CurrentMessage: "hello"})
+	system := messages[0]
+	if !strings.Contains(system.Content, "tool_search_tool_bm25") {
+		t.Fatalf("system prompt missing tool discovery rule: %q", system.Content)
+	}
+
+	var found bool
+	for _, part := range system.SystemParts {
+		if part.PromptSource == string(PromptSourceToolDiscovery) {
+			found = true
+			if part.PromptLayer != string(PromptLayerCapability) || part.PromptSlot != string(PromptSlotTooling) {
+				t.Fatalf("tool discovery metadata = %#v, want capability/tooling", part)
+			}
+			if part.CacheControl == nil || part.CacheControl.Type != "ephemeral" {
+				t.Fatalf("tool discovery cache control = %#v, want ephemeral", part.CacheControl)
+			}
+		}
+	}
+	if !found {
+		t.Fatal("system parts missing tool discovery prompt metadata")
+	}
+}
+
+func TestContextBuilder_CollectsMCPServerContributor(t *testing.T) {
+	t.Setenv("PICOCLAW_BUILTIN_SKILLS", t.TempDir())
+	cb := NewContextBuilder(t.TempDir())
+	err := cb.RegisterPromptContributor(mcpServerPromptContributor{
+		serverName: "GitHub Server",
+		toolCount:  3,
+		deferred:   true,
+	})
+	if err != nil {
+		t.Fatalf("RegisterPromptContributor() error = %v", err)
+	}
+
+	messages := cb.BuildMessagesFromPrompt(PromptBuildRequest{CurrentMessage: "hello"})
+	system := messages[0]
+	if !strings.Contains(system.Content, "MCP server `GitHub Server` is connected") {
+		t.Fatalf("system prompt missing MCP contributor content: %q", system.Content)
+	}
+
+	var found bool
+	for _, part := range system.SystemParts {
+		if part.PromptSource == "mcp:github_server" {
+			found = true
+			if part.PromptLayer != string(PromptLayerCapability) || part.PromptSlot != string(PromptSlotMCP) {
+				t.Fatalf("mcp metadata = %#v, want capability/mcp", part)
+			}
+			if part.CacheControl == nil || part.CacheControl.Type != "ephemeral" {
+				t.Fatalf("mcp cache control = %#v, want ephemeral", part.CacheControl)
+			}
+		}
+	}
+	if !found {
+		t.Fatal("system parts missing MCP prompt metadata")
+	}
+}
+
+type testPromptContributor struct {
+	desc PromptSourceDescriptor
+	part PromptPart
+}
+
+func (c testPromptContributor) PromptSource() PromptSourceDescriptor {
+	return c.desc
+}
+
+func (c testPromptContributor) ContributePrompt(_ context.Context, _ PromptBuildRequest) ([]PromptPart, error) {
+	return []PromptPart{c.part}, nil
+}
+
+func TestContextBuilder_CollectsRegisteredPromptContributors(t *testing.T) {
+	t.Setenv("PICOCLAW_BUILTIN_SKILLS", t.TempDir())
+	cb := NewContextBuilder(t.TempDir())
+
+	sourceID := PromptSourceID("test:contributor")
+	err := cb.RegisterPromptContributor(testPromptContributor{
+		desc: PromptSourceDescriptor{
+			ID:      sourceID,
+			Owner:   "test",
+			Allowed: []PromptPlacement{{Layer: PromptLayerCapability, Slot: PromptSlotMCP}},
+		},
+		part: PromptPart{
+			ID:      "capability.mcp.test",
+			Layer:   PromptLayerCapability,
+			Slot:    PromptSlotMCP,
+			Source:  PromptSource{ID: sourceID, Name: "test"},
+			Content: "registered contributor prompt",
+		},
+	})
+	if err != nil {
+		t.Fatalf("RegisterPromptContributor() error = %v", err)
+	}
+
+	messages := cb.BuildMessagesFromPrompt(PromptBuildRequest{CurrentMessage: "hello"})
+	if !strings.Contains(messages[0].Content, "registered contributor prompt") {
+		t.Fatalf("system prompt missing contributor content: %q", messages[0].Content)
+	}
+}

pkg/agent/prompt_turn.go

@@ -0,0 +1,129 @@
+package agent
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func promptBuildRequestForTurn(
+	ts *turnState,
+	history []providers.Message,
+	summary string,
+	currentMessage string,
+	media []string,
+) PromptBuildRequest {
+	return PromptBuildRequest{
+		History:           history,
+		Summary:           summary,
+		CurrentMessage:    currentMessage,
+		Media:             append([]string(nil), media...),
+		Channel:           ts.channel,
+		ChatID:            ts.chatID,
+		SenderID:          ts.opts.Dispatch.SenderID(),
+		SenderDisplayName: ts.opts.SenderDisplayName,
+		ActiveSkills:      activeSkillNames(ts.agent, ts.opts),
+		Overlays:          promptOverlaysForOptions(ts.opts),
+	}
+}
+
+func promptOverlaysForOptions(opts processOptions) []PromptPart {
+	systemPrompt := strings.TrimSpace(opts.SystemPromptOverride)
+	if systemPrompt == "" {
+		return nil
+	}
+
+	return []PromptPart{
+		{
+			ID:      "instruction.subturn_profile",
+			Layer:   PromptLayerInstruction,
+			Slot:    PromptSlotWorkspace,
+			Source:  PromptSource{ID: PromptSourceSubTurnProfile, Name: "subturn.profile"},
+			Title:   "SubTurn System Instructions",
+			Content: systemPrompt,
+			Stable:  false,
+			Cache:   PromptCacheNone,
+		},
+	}
+}
+
+func promptContentBlock(part PromptPart, cache *providers.CacheControl) providers.ContentBlock {
+	if cache == nil {
+		cache = cacheControlForPromptPart(part)
+	}
+	return providers.ContentBlock{
+		Type:         "text",
+		Text:         part.Content,
+		CacheControl: cache,
+		PromptLayer:  string(part.Layer),
+		PromptSlot:   string(part.Slot),
+		PromptSource: string(part.Source.ID),
+	}
+}
+
+func cacheControlForPromptPart(part PromptPart) *providers.CacheControl {
+	switch part.Cache {
+	case PromptCacheEphemeral:
+		return &providers.CacheControl{Type: "ephemeral"}
+	default:
+		return nil
+	}
+}
+
+func promptMessageWithMetadata(
+	msg providers.Message,
+	layer PromptLayer,
+	slot PromptSlot,
+	source PromptSourceID,
+) providers.Message {
+	msg.PromptLayer = string(layer)
+	msg.PromptSlot = string(slot)
+	msg.PromptSource = string(source)
+	return msg
+}
+
+func promptMessageWithDefaultMetadata(
+	msg providers.Message,
+	layer PromptLayer,
+	slot PromptSlot,
+	source PromptSourceID,
+) providers.Message {
+	if strings.TrimSpace(msg.PromptSource) != "" {
+		return msg
+	}
+	return promptMessageWithMetadata(msg, layer, slot, source)
+}
+
+func userPromptMessage(content string, media []string) providers.Message {
+	msg := providers.Message{
+		Role:    "user",
+		Content: content,
+	}
+	if len(media) > 0 {
+		msg.Media = append([]string(nil), media...)
+	}
+	return promptMessageWithMetadata(msg, PromptLayerTurn, PromptSlotMessage, PromptSourceUserMessage)
+}
+
+func steeringPromptMessage(msg providers.Message) providers.Message {
+	return promptMessageWithDefaultMetadata(msg, PromptLayerTurn, PromptSlotSteering, PromptSourceSteering)
+}
+
+func subTurnResultPromptMessage(content string) providers.Message {
+	return promptMessageWithMetadata(
+		providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", content)},
+		PromptLayerTurn,
+		PromptSlotSubTurn,
+		PromptSourceSubTurnResult,
+	)
+}
+
+func interruptPromptMessage(content string) providers.Message {
+	return promptMessageWithMetadata(
+		providers.Message{Role: "user", Content: content},
+		PromptLayerTurn,
+		PromptSlotInterrupt,
+		PromptSourceInterrupt,
+	)
+}

pkg/agent/steering.go

@@ -187,6 +187,7 @@ func (al *AgentLoop) enqueueSteeringMessage(scope, agentID string, msg providers
 		return fmt.Errorf("steering queue is not initialized")
 	}
 
+	msg = steeringPromptMessage(msg)
 	if err := al.steering.pushScope(scope, msg); err != nil {
 		logger.WarnCF("agent", "Failed to enqueue steering message", map[string]any{
 			"error": err.Error(),

pkg/agent/steering_test.go

@@ -1051,16 +1051,16 @@ func TestAgentLoop_Continue_PreservesSteeringMedia(t *testing.T) {
 
 	foundResolvedMedia := false
 	for _, msg := range msgs {
-		if msg.Role != "user" || msg.Content != "describe this image" || len(msg.Media) != 1 {
+		if msg.Role != "user" || !strings.Contains(msg.Content, "describe this image") {
 			continue
 		}
-		if strings.HasPrefix(msg.Media[0], "data:image/png;base64,") {
+		if strings.Contains(msg.Content, "[image:") {
 			foundResolvedMedia = true
 			break
 		}
 	}
 	if !foundResolvedMedia {
-		t.Fatal("expected continue path to inject steering media into the provider request")
+		t.Fatal("expected continue path to inject image path tag into the provider request")
 	}
 
 	defaultAgent := al.registry.GetDefaultAgent()

pkg/agent/subturn.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/providers/messageutil"
 	"github.com/sipeed/picoclaw/pkg/tools"
 )
 
@@ -623,6 +624,10 @@ func (e *ephemeralSessionStore) AddMessage(_, role, content string) {
 }
 
 func (e *ephemeralSessionStore) AddFullMessage(_ string, msg providers.Message) {
+	if messageutil.IsTransientAssistantThoughtMessage(msg) {
+		return
+	}
+
 	e.mu.Lock()
 	defer e.mu.Unlock()
 	e.history = append(e.history, msg)
@@ -652,6 +657,7 @@ func (e *ephemeralSessionStore) SetSummary(_, summary string) {
 func (e *ephemeralSessionStore) SetHistory(_ string, history []providers.Message) {
 	e.mu.Lock()
 	defer e.mu.Unlock()
+	history = messageutil.FilterInvalidHistoryMessages(history)
 	e.history = make([]providers.Message, len(history))
 	copy(e.history, history)
 	e.truncateLocked()

pkg/agent/turn_coord.go

@@ -111,7 +111,7 @@ func (al *AgentLoop) runTurn(ctx context.Context, ts *turnState, pipeline *Pipel
 			case result, ok := <-ts.pendingResults:
 				if ok && result != nil && result.ForLLM != "" {
 					content := al.cfg.FilterSensitiveData(result.ForLLM)
-					msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", content)}
+					msg := subTurnResultPromptMessage(content)
 					pendingMessages = append(pendingMessages, msg)
 				}
 			default:

pkg/agent/turn_state.go

@@ -527,10 +527,7 @@ func (ts *turnState) interruptHintMessage() providers.Message {
 	if hint != "" {
 		content += "\n\nInterrupt hint: " + hint
 	}
-	return providers.Message{
-		Role:    "user",
-		Content: content,
-	}
+	return interruptPromptMessage(content)
 }
 
 // =============================================================================

pkg/channels/feishu/common.go

@@ -64,6 +64,62 @@ func extractJSONStringField(content, field string) string {
 // Format: {"image_key": "img_xxx"}
 func extractImageKey(content string) string { return extractJSONStringField(content, "image_key") }
 
+// extractPostImageKeys extracts all image_key values from a Feishu post (rich text)
+// message. Post messages have nested arrays of elements where images appear as
+// {"tag":"img","image_key":"img_xxx"}.
+func extractPostImageKeys(rawContent string) []string {
+	if rawContent == "" {
+		return nil
+	}
+
+	var post map[string]json.RawMessage
+	if err := json.Unmarshal([]byte(rawContent), &post); err != nil {
+		return nil
+	}
+
+	var keys []string
+	seen := make(map[string]struct{})
+
+	collectFromRows := func(contentRaw json.RawMessage) {
+		var rows [][]map[string]any
+		if err := json.Unmarshal(contentRaw, &rows); err != nil {
+			return
+		}
+		for _, row := range rows {
+			for _, elem := range row {
+				if tag, _ := elem["tag"].(string); tag == "img" {
+					if ik, _ := elem["image_key"].(string); ik != "" {
+						if _, dup := seen[ik]; !dup {
+							seen[ik] = struct{}{}
+							keys = append(keys, ik)
+						}
+					}
+				}
+			}
+		}
+	}
+
+	// Flat format: {"title":"...", "content":[[...]]}
+	if contentRaw, ok := post["content"]; ok {
+		collectFromRows(contentRaw)
+	}
+
+	// Localized format: {"zh_cn": {"title":"...", "content":[[...]]}, ...}
+	for _, raw := range post {
+		var locale map[string]json.RawMessage
+		if err := json.Unmarshal(raw, &locale); err != nil {
+			continue
+		}
+		contentRaw, ok := locale["content"]
+		if !ok {
+			continue
+		}
+		collectFromRows(contentRaw)
+	}
+
+	return keys
+}
+
 // extractFileKey extracts the file_key from a Feishu file/audio message content JSON.
 // Format: {"file_key": "file_xxx", "file_name": "...", ...}
 func extractFileKey(content string) string { return extractJSONStringField(content, "file_key") }

pkg/channels/feishu/common_test.go

@@ -291,6 +291,100 @@ func TestStripMentionPlaceholders(t *testing.T) {
 	}
 }
 
+func TestExtractPostImageKeys(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    []string
+	}{
+		{
+			name:    "empty content",
+			content: "",
+			want:    nil,
+		},
+		{
+			name:    "invalid JSON",
+			content: "not json",
+			want:    nil,
+		},
+		{
+			name:    "post with no images",
+			content: `{"zh_cn":{"title":"Title","content":[[{"tag":"text","text":"hello"}]]}}`,
+			want:    nil,
+		},
+		{
+			name:    "post with one image",
+			content: `{"zh_cn":{"title":"","content":[[{"tag":"img","image_key":"img_v3_001"}]]}}`,
+			want:    []string{"img_v3_001"},
+		},
+		{
+			name:    "post with multiple images",
+			content: `{"zh_cn":{"title":"","content":[[{"tag":"text","text":"see"},{"tag":"img","image_key":"img_001"}],[{"tag":"img","image_key":"img_002"}]]}}`,
+			want:    []string{"img_001", "img_002"},
+		},
+		{
+			name:    "post with text and image mixed in row",
+			content: `{"zh_cn":{"title":"","content":[[{"tag":"text","text":"hi"},{"tag":"img","image_key":"img_mix"}]]}}`,
+			want:    []string{"img_mix"},
+		},
+		{
+			name:    "en_us locale",
+			content: `{"en_us":{"title":"","content":[[{"tag":"img","image_key":"img_en"}]]}}`,
+			want:    []string{"img_en"},
+		},
+		{
+			name:    "multiple locales with distinct images",
+			content: `{"zh_cn":{"title":"","content":[[{"tag":"img","image_key":"img_zh"}]]},"en_us":{"title":"","content":[[{"tag":"img","image_key":"img_en"}]]}}`,
+			want:    []string{"img_zh", "img_en"},
+		},
+		{
+			name:    "duplicate image_key across locales is deduplicated",
+			content: `{"zh_cn":{"title":"","content":[[{"tag":"img","image_key":"img_same"}]]},"en_us":{"title":"","content":[[{"tag":"img","image_key":"img_same"}]]}}`,
+			want:    []string{"img_same"},
+		},
+		{
+			name:    "image with empty image_key",
+			content: `{"zh_cn":{"title":"","content":[[{"tag":"img","image_key":""}]]}}`,
+			want:    nil,
+		},
+		{
+			name:    "flat format without locale wrapper",
+			content: `{"title":"","content":[[{"tag":"img","image_key":"img_v3_flat","width":1826,"height":338}],[{"tag":"text","text":" check this image","style":[]}]]}`,
+			want:    []string{"img_v3_flat"},
+		},
+		{
+			name:    "flat format multiple images",
+			content: `{"title":"","content":[[{"tag":"img","image_key":"img_flat_1"}],[{"tag":"img","image_key":"img_flat_2"},{"tag":"text","text":"desc"}]]}`,
+			want:    []string{"img_flat_1", "img_flat_2"},
+		},
+		{
+			name:    "flat format no images",
+			content: `{"title":"Test","content":[[{"tag":"text","text":"just text"}]]}`,
+			want:    nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractPostImageKeys(tt.content)
+			if len(got) != len(tt.want) {
+				t.Errorf("extractPostImageKeys() = %v, want %v", got, tt.want)
+				return
+			}
+			// Use set comparison to avoid map iteration order dependency
+			gotSet := make(map[string]bool, len(got))
+			for _, v := range got {
+				gotSet[v] = true
+			}
+			for _, v := range tt.want {
+				if !gotSet[v] {
+					t.Errorf("extractPostImageKeys() missing expected key %q; got %v", v, got)
+				}
+			}
+		})
+	}
+}
+
 func TestExtractCardImageKeys(t *testing.T) {
 	tests := []struct {
 		name             string

pkg/channels/feishu/feishu_64.go

@@ -803,6 +803,14 @@ func (c *FeishuChannel) downloadInboundMedia(
 			refs = append(refs, ref)
 		}
 
+	case larkim.MsgTypePost:
+		for _, imageKey := range extractPostImageKeys(rawContent) {
+			ref := c.downloadResource(ctx, messageID, imageKey, "image", ".jpg", store, scope)
+			if ref != "" {
+				refs = append(refs, ref)
+			}
+		}
+
 	case larkim.MsgTypeInteractive:
 		// Extract and download images embedded in interactive cards
 		feishuKeys, _ := extractCardImageKeys(rawContent)
@@ -842,12 +850,41 @@ func (c *FeishuChannel) downloadInboundMedia(
 // downloadResource downloads a message resource (image/file) from Feishu,
 // writes it to the project media directory, and stores the reference in MediaStore.
 // fallbackExt (e.g. ".jpg") is appended when the resolved filename has no extension.
+//
+// For image resources, if the primary MessageResource.Get API fails (which
+// requires im:message or im:message:readonly scope), a fallback to the
+// Image.Get API (which requires im:resource scope) is attempted. This ensures
+// image downloads succeed regardless of which permission the user has granted.
 func (c *FeishuChannel) downloadResource(
 	ctx context.Context,
 	messageID, fileKey, resourceType, fallbackExt string,
 	store media.MediaStore,
 	scope string,
 ) string {
+	file, filename := c.fetchResourceData(ctx, messageID, fileKey, resourceType)
+	if file == nil {
+		return ""
+	}
+	if closer, ok := file.(io.Closer); ok {
+		defer closer.Close()
+	}
+
+	if filename == "" {
+		filename = fileKey
+	}
+	if filepath.Ext(filename) == "" && fallbackExt != "" {
+		filename += fallbackExt
+	}
+
+	return c.storeResourceFile(ctx, messageID, fileKey, filename, file, store, scope)
+}
+
+// fetchResourceData tries to download a resource from Feishu, first via
+// MessageResource.Get, then falling back to Image.Get for image resources.
+func (c *FeishuChannel) fetchResourceData(
+	ctx context.Context,
+	messageID, fileKey, resourceType string,
+) (io.Reader, string) {
 	req := larkim.NewGetMessageResourceReqBuilder().
 		MessageId(messageID).
 		FileKey(fileKey).
@@ -855,41 +892,80 @@ func (c *FeishuChannel) downloadResource(
 		Build()
 
 	resp, err := c.client.Im.V1.MessageResource.Get(ctx, req)
+	if err == nil && resp.Success() && resp.File != nil {
+		return resp.File, resp.FileName
+	}
+
 	if err != nil {
-		logger.ErrorCF("feishu", "Failed to download resource", map[string]any{
+		logger.WarnCF("feishu", "MessageResource.Get failed", map[string]any{
 			"message_id": messageID,
 			"file_key":   fileKey,
 			"error":      err.Error(),
 		})
-		return ""
+	} else if !resp.Success() {
+		c.invalidateTokenOnAuthError(resp.Code)
+		logger.WarnCF("feishu", "MessageResource.Get api error", map[string]any{
+			"message_id": messageID,
+			"file_key":   fileKey,
+			"code":       resp.Code,
+			"msg":        resp.Msg,
+		})
+	} else {
+		logger.WarnCF("feishu", "MessageResource.Get returned empty file body", map[string]any{
+			"message_id": messageID,
+			"file_key":   fileKey,
+		})
+	}
+
+	if resourceType != "image" {
+		return nil, ""
+	}
+
+	return c.fetchImageDirect(ctx, fileKey)
+}
+
+// fetchImageDirect downloads an image using the Image.Get API
+// (/open-apis/im/v1/images/:image_key), which requires the im:resource scope.
+func (c *FeishuChannel) fetchImageDirect(ctx context.Context, imageKey string) (io.Reader, string) {
+	req := larkim.NewGetImageReqBuilder().
+		ImageKey(imageKey).
+		Build()
+
+	resp, err := c.client.Im.V1.Image.Get(ctx, req)
+	if err != nil {
+		logger.ErrorCF("feishu", "Image.Get fallback failed", map[string]any{
+			"image_key": imageKey,
+			"error":     err.Error(),
+		})
+		return nil, ""
 	}
 	if !resp.Success() {
 		c.invalidateTokenOnAuthError(resp.Code)
-		logger.ErrorCF("feishu", "Resource download api error", map[string]any{
-			"code": resp.Code,
-			"msg":  resp.Msg,
+		logger.ErrorCF("feishu", "Image.Get fallback api error", map[string]any{
+			"image_key": imageKey,
+			"code":      resp.Code,
+			"msg":       resp.Msg,
 		})
-		return ""
+		return nil, ""
 	}
-
 	if resp.File == nil {
-		return ""
-	}
-	// Safely close the underlying reader if it implements io.Closer (e.g. HTTP response body).
-	if closer, ok := resp.File.(io.Closer); ok {
-		defer closer.Close()
+		return nil, ""
 	}
 
-	filename := resp.FileName
-	if filename == "" {
-		filename = fileKey
-	}
-	// If filename still has no extension, append the fallback (like Telegram's ext parameter).
-	if filepath.Ext(filename) == "" && fallbackExt != "" {
-		filename += fallbackExt
-	}
+	logger.DebugCF("feishu", "Image downloaded via Image.Get fallback", map[string]any{
+		"image_key": imageKey,
+	})
+	return resp.File, resp.FileName
+}
 
-	// Write to the shared picoclaw_media directory using a unique name to avoid collisions.
+// storeResourceFile writes downloaded resource data to disk and registers it in the MediaStore.
+func (c *FeishuChannel) storeResourceFile(
+	ctx context.Context,
+	messageID, fileKey, filename string,
+	file io.Reader,
+	store media.MediaStore,
+	scope string,
+) string {
 	mediaDir := media.TempDir()
 	if mkdirErr := os.MkdirAll(mediaDir, 0o700); mkdirErr != nil {
 		logger.ErrorCF("feishu", "Failed to create media directory", map[string]any{
@@ -908,7 +984,7 @@ func (c *FeishuChannel) downloadResource(
 		return ""
 	}
 
-	if _, copyErr := io.Copy(out, resp.File); copyErr != nil {
+	if _, copyErr := io.Copy(out, file); copyErr != nil {
 		out.Close()
 		os.Remove(localPath)
 		logger.ErrorCF("feishu", "Failed to write resource to file", map[string]any{
@@ -943,8 +1019,8 @@ func appendMediaTags(content, messageType string, mediaRefs []string) string {
 		return content
 	}
 
-	// Don't append tags to JSON content (interactive cards) - would produce invalid JSON
-	if messageType == larkim.MsgTypeInteractive {
+	// Don't append tags to JSON content - would produce invalid JSON
+	if messageType == larkim.MsgTypeInteractive || messageType == larkim.MsgTypePost {
 		return content
 	}
 

pkg/channels/feishu/feishu_64_test.go

@@ -180,6 +180,13 @@ func TestAppendMediaTags(t *testing.T) {
 			mediaRefs:   []string{"ref1"},
 			want:        `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`,
 		},
+		{
+			name:        "post message with images returns content unchanged",
+			content:     `{"zh_cn":{"title":"","content":[[{"tag":"img","image_key":"img_001"}]]}}`,
+			messageType: "post",
+			mediaRefs:   []string{"ref1"},
+			want:        `{"zh_cn":{"title":"","content":[[{"tag":"img","image_key":"img_001"}]]}}`,
+		},
 	}
 
 	for _, tt := range tests {

pkg/channels/manager.go

@@ -134,6 +134,14 @@ func outboundMessageIsToolFeedback(msg bus.OutboundMessage) bool {
 	return strings.EqualFold(strings.TrimSpace(msg.Context.Raw["message_kind"]), "tool_feedback")
 }
 
+func outboundMessageBypassesPlaceholderEdit(msg bus.OutboundMessage) bool {
+	if len(msg.Context.Raw) == 0 {
+		return false
+	}
+	kind := strings.TrimSpace(msg.Context.Raw["message_kind"])
+	return strings.EqualFold(kind, "thought") || strings.EqualFold(kind, "tool_calls")
+}
+
 func outboundMediaChannel(msg bus.OutboundMediaMessage) string {
 	return msg.Context.Channel
 }
@@ -170,6 +178,35 @@ func dismissTrackedToolFeedbackMessage(
 	}
 }
 
+func clearTrackedToolFeedbackMessage(
+	ch Channel,
+	chatID string,
+	outboundCtx *bus.InboundContext,
+) {
+	trackedChatID := trackedToolFeedbackMessageChatID(ch, chatID, outboundCtx)
+	if trackedChatID == "" {
+		return
+	}
+	if tracker, ok := ch.(toolFeedbackMessageTracker); ok {
+		tracker.ClearToolFeedbackMessage(trackedChatID)
+	}
+}
+
+// DismissToolFeedback clears any tracked tool feedback animation for the
+// given channel/chat. This is called when a turn ends without a final
+// response (e.g., ResponseHandled tools) to stop orphaned animation goroutines.
+// outboundCtx carries topic/thread info for channels that use scoped tracker
+// keys (e.g., Telegram forum topics); may be nil for non-topic channels.
+func (m *Manager) DismissToolFeedback(
+	ctx context.Context, channelName, chatID string, outboundCtx *bus.InboundContext,
+) {
+	ch, ok := m.GetChannel(channelName)
+	if !ok {
+		return
+	}
+	dismissTrackedToolFeedbackMessage(ctx, ch, chatID, outboundCtx)
+}
+
 func prepareToolFeedbackMessageContent(ch Channel, content string) string {
 	prepared := strings.TrimSpace(content)
 	if prepared == "" {
@@ -183,6 +220,13 @@ func prepareToolFeedbackMessageContent(ch Channel, content string) string {
 	return prepared
 }
 
+func (m *Manager) toolFeedbackSeparateMessagesEnabled() bool {
+	if m == nil || m.config == nil {
+		return false
+	}
+	return m.config.Agents.Defaults.IsToolFeedbackSeparateMessagesEnabled()
+}
+
 // RecordPlaceholder registers a placeholder message for later editing.
 // Implements PlaceholderRecorder.
 func (m *Manager) RecordPlaceholder(channel, chatID, placeholderID string) {
@@ -264,6 +308,7 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess
 	}
 
 	isToolFeedback := outboundMessageIsToolFeedback(msg)
+	separateToolFeedbackMessages := m.toolFeedbackSeparateMessagesEnabled()
 
 	// 3. If a stream already finalized this chat, stale tool feedback must be
 	// dropped without consuming the final-response marker. Streaming finalization
@@ -288,14 +333,34 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess
 			}
 		}
 		if !isToolFeedback {
-			dismissTrackedToolFeedbackMessage(ctx, ch, chatID, &msg.Context)
+			if separateToolFeedbackMessages {
+				clearTrackedToolFeedbackMessage(ch, chatID, &msg.Context)
+			} else {
+				dismissTrackedToolFeedbackMessage(ctx, ch, chatID, &msg.Context)
+			}
 		}
 		return nil, true
 	}
 
+	if separateToolFeedbackMessages {
+		clearTrackedToolFeedbackMessage(ch, chatID, &msg.Context)
+	}
+
 	// 5. Try editing placeholder
 	if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
 		if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
+			if isToolFeedback && separateToolFeedbackMessages {
+				if deleter, ok := ch.(MessageDeleter); ok {
+					deleter.DeleteMessage(ctx, chatID, entry.id) // best effort
+				}
+				return nil, false
+			}
+			if outboundMessageBypassesPlaceholderEdit(msg) {
+				if deleter, ok := ch.(MessageDeleter); ok {
+					deleter.DeleteMessage(ctx, chatID, entry.id) // best effort
+				}
+				return nil, false
+			}
 			if editor, ok := ch.(MessageEditor); ok {
 				content := msg.Content
 				trackedContent := msg.Content
@@ -345,6 +410,10 @@ func (m *Manager) preSendMedia(ctx context.Context, name string, msg bus.Outboun
 	// 3. Clear any finalized stream marker for this chat before media delivery.
 	m.streamActive.LoadAndDelete(key)
 
+	if m.toolFeedbackSeparateMessagesEnabled() {
+		clearTrackedToolFeedbackMessage(ch, chatID, &msg.Context)
+	}
+
 	// 4. Delete placeholder if present.
 	if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
 		if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
@@ -408,15 +477,26 @@ func (m *Manager) GetStreamer(ctx context.Context, channelName, chatID string) (
 	return &finalizeHookStreamer{
 		Streamer: streamer,
 		onFinalize: func(finalizeCtx context.Context) {
-			dismissTrackedToolFeedbackMessage(
-				finalizeCtx,
-				ch,
-				chatID,
-				&bus.InboundContext{
-					Channel: channelName,
-					ChatID:  chatID,
-				},
-			)
+			if m.toolFeedbackSeparateMessagesEnabled() {
+				clearTrackedToolFeedbackMessage(
+					ch,
+					chatID,
+					&bus.InboundContext{
+						Channel: channelName,
+						ChatID:  chatID,
+					},
+				)
+			} else {
+				dismissTrackedToolFeedbackMessage(
+					finalizeCtx,
+					ch,
+					chatID,
+					&bus.InboundContext{
+						Channel: channelName,
+						ChatID:  chatID,
+					},
+				)
+			}
 			m.streamActive.Store(key, true)
 		},
 	}, true

pkg/channels/manager_test.go

@@ -804,6 +804,20 @@ type mockResolvedToolFeedbackEditor struct {
 	resolveChatIDFn func(chatID string, outboundCtx *bus.InboundContext) string
 }
 
+type mockDeletingMessageEditor struct {
+	mockMessageEditor
+	deleteCalls      int
+	deletedChatID    string
+	deletedMessageID string
+}
+
+func (m *mockDeletingMessageEditor) DeleteMessage(_ context.Context, chatID, messageID string) error {
+	m.deleteCalls++
+	m.deletedChatID = chatID
+	m.deletedMessageID = messageID
+	return nil
+}
+
 func (m *mockResolvedToolFeedbackEditor) ToolFeedbackMessageChatID(
 	chatID string,
 	outboundCtx *bus.InboundContext,
@@ -1062,6 +1076,202 @@ func TestPreSend_NonToolFeedbackDefersTrackedMessageFinalizationToChannelSend(t
 	}
 }
 
+func TestPreSend_ToolFeedbackSeparateMessagesDeletesPlaceholderAndSkipsEdit(t *testing.T) {
+	m := newTestManager()
+	m.config = &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ToolFeedback: config.ToolFeedbackConfig{
+					Enabled:          true,
+					SeparateMessages: true,
+				},
+			},
+		},
+	}
+
+	ch := &mockDeletingMessageEditor{
+		mockMessageEditor: mockMessageEditor{
+			editFn: func(_ context.Context, _, _, _ string) error {
+				t.Fatal("expected placeholder edit to be skipped in separate message mode")
+				return nil
+			},
+		},
+	}
+
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := testOutboundMessage(bus.OutboundMessage{
+		Channel: "test",
+		ChatID:  "123",
+		Content: "hello",
+		Context: bus.InboundContext{
+			Channel: "test",
+			ChatID:  "123",
+			Raw: map[string]string{
+				"message_kind": "tool_feedback",
+			},
+		},
+	})
+
+	msgIDs, handled := m.preSend(context.Background(), "test", msg, ch)
+	if handled {
+		t.Fatalf("expected preSend to fall through so the channel can send a new message, got %v", msgIDs)
+	}
+	if ch.deleteCalls != 1 {
+		t.Fatalf("expected placeholder deletion, got %d delete calls", ch.deleteCalls)
+	}
+	if ch.deletedChatID != "123" || ch.deletedMessageID != "456" {
+		t.Fatalf("unexpected placeholder deletion target: %s/%s", ch.deletedChatID, ch.deletedMessageID)
+	}
+	if ch.recordedMessageID != "" {
+		t.Fatalf("expected no tracked placeholder record, got %q", ch.recordedMessageID)
+	}
+	if ch.clearedChatID != "123" {
+		t.Fatalf("expected tracked tool feedback state to be cleared before sending, got %q", ch.clearedChatID)
+	}
+}
+
+func TestPreSend_ThoughtPlaceholderDeleteAndSkipsEdit(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockDeletingMessageEditor{
+		mockMessageEditor: mockMessageEditor{
+			editFn: func(_ context.Context, _, _, _ string) error {
+				t.Fatal("expected thought message to bypass placeholder edit")
+				return nil
+			},
+		},
+	}
+
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := testOutboundMessage(bus.OutboundMessage{
+		Channel: "test",
+		ChatID:  "123",
+		Content: "thinking trace",
+		Context: bus.InboundContext{
+			Channel: "test",
+			ChatID:  "123",
+			Raw: map[string]string{
+				"message_kind": "thought",
+			},
+		},
+	})
+
+	msgIDs, handled := m.preSend(context.Background(), "test", msg, ch)
+	if handled {
+		t.Fatalf(
+			"expected thought message to fall through so the channel can send a structured message, got %v",
+			msgIDs,
+		)
+	}
+	if ch.deleteCalls != 1 {
+		t.Fatalf("expected placeholder deletion, got %d delete calls", ch.deleteCalls)
+	}
+	if ch.deletedChatID != "123" || ch.deletedMessageID != "456" {
+		t.Fatalf("unexpected placeholder deletion target: %s/%s", ch.deletedChatID, ch.deletedMessageID)
+	}
+	if _, ok := m.placeholders.Load("test:123"); ok {
+		t.Fatal("expected placeholder to be consumed before structured thought send")
+	}
+}
+
+func TestSendWithRetry_ToolCallsPlaceholderDeleteAndFallsThroughToSend(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockDeletingMessageEditor{
+		mockMessageEditor: mockMessageEditor{
+			mockChannel: mockChannel{
+				sendFn: func(_ context.Context, msg bus.OutboundMessage) error {
+					if got := msg.Context.Raw["message_kind"]; got != "tool_calls" {
+						t.Fatalf("expected tool_calls message kind, got %q", got)
+					}
+					if msg.Content != "" {
+						t.Fatalf("expected empty tool_calls content, got %q", msg.Content)
+					}
+					return nil
+				},
+			},
+			editFn: func(_ context.Context, _, _, _ string) error {
+				t.Fatal("expected tool_calls message to bypass placeholder edit")
+				return nil
+			},
+		},
+	}
+
+	m.RecordPlaceholder("test", "123", "456")
+
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	msg := testOutboundMessage(bus.OutboundMessage{
+		Channel: "test",
+		ChatID:  "123",
+		Context: bus.InboundContext{
+			Channel: "test",
+			ChatID:  "123",
+			Raw: map[string]string{
+				"message_kind": "tool_calls",
+				"tool_calls":   `[{"id":"call_1","type":"function","function":{"name":"read_file","arguments":"{}"},"extra_content":{"tool_feedback_explanation":"Looking up config"}}]`,
+			},
+		},
+	})
+
+	m.sendWithRetry(context.Background(), "test", w, msg)
+
+	if ch.deleteCalls != 1 {
+		t.Fatalf("expected placeholder deletion, got %d delete calls", ch.deleteCalls)
+	}
+	if ch.deletedChatID != "123" || ch.deletedMessageID != "456" {
+		t.Fatalf("unexpected placeholder deletion target: %s/%s", ch.deletedChatID, ch.deletedMessageID)
+	}
+	if len(ch.sentMessages) != 1 {
+		t.Fatalf("expected structured tool_calls message to be sent once, got %d", len(ch.sentMessages))
+	}
+}
+
+func TestPreSend_NonToolFeedbackSeparateMessagesClearsTrackedMessageWithoutDismiss(t *testing.T) {
+	m := newTestManager()
+	m.config = &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ToolFeedback: config.ToolFeedbackConfig{
+					Enabled:          true,
+					SeparateMessages: true,
+				},
+			},
+		},
+	}
+
+	ch := &mockMessageEditor{}
+
+	msg := testOutboundMessage(bus.OutboundMessage{
+		Channel: "test",
+		ChatID:  "123",
+		Content: "final reply",
+		Context: bus.InboundContext{
+			Channel: "test",
+			ChatID:  "123",
+		},
+	})
+
+	_, handled := m.preSend(context.Background(), "test", msg, ch)
+	if handled {
+		t.Fatal("expected preSend to leave final delivery to the channel")
+	}
+	if ch.clearedChatID != "123" {
+		t.Fatalf("expected tracked tool feedback state to be cleared, got %q", ch.clearedChatID)
+	}
+	if ch.dismissedChatID != "" {
+		t.Fatalf("expected tracked tool feedback message to be preserved, got dismissal for %q", ch.dismissedChatID)
+	}
+	if ch.finalizeCalled {
+		t.Fatal("expected separate message mode to skip in-place finalization")
+	}
+}
+
 func TestPreSend_StaleToolFeedbackDoesNotConsumeStreamActiveMarker(t *testing.T) {
 	m := newTestManager()
 	m.streamActive.Store("test:123", true)
@@ -1153,6 +1363,38 @@ func TestPreSendMedia_LeavesTrackedMessageForChannelSend(t *testing.T) {
 	}
 }
 
+func TestPreSendMedia_SeparateMessagesClearsTrackedMessageWithoutDismiss(t *testing.T) {
+	m := newTestManager()
+	m.config = &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ToolFeedback: config.ToolFeedbackConfig{
+					Enabled:          true,
+					SeparateMessages: true,
+				},
+			},
+		},
+	}
+
+	ch := &mockMessageEditor{}
+
+	m.preSendMedia(context.Background(), "test", bus.OutboundMediaMessage{
+		ChatID: "123",
+		Context: bus.InboundContext{
+			Channel: "test",
+			ChatID:  "123",
+		},
+	}, ch)
+
+	if ch.clearedChatID != "123" {
+		t.Fatalf("expected tracked tool feedback state to be cleared before media delivery, got %q", ch.clearedChatID)
+	}
+	if ch.dismissedChatID != "" {
+		t.Fatalf("expected tracked tool feedback message to be preserved"+
+			" for media delivery, got %q", ch.dismissedChatID)
+	}
+}
+
 func TestSplitOutboundMessageContent_ToolFeedbackTruncatesInsteadOfSplitting(t *testing.T) {
 	msg := testOutboundMessage(bus.OutboundMessage{
 		Channel: "test",
@@ -1232,6 +1474,49 @@ func TestGetStreamer_FinalizeDismissesTrackedToolFeedback(t *testing.T) {
 	}
 }
 
+func TestGetStreamer_FinalizeSeparateMessagesClearsTrackedToolFeedback(t *testing.T) {
+	m := newTestManager()
+	m.config = &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ToolFeedback: config.ToolFeedbackConfig{
+					Enabled:          true,
+					SeparateMessages: true,
+				},
+			},
+		},
+	}
+	ch := &mockStreamingChannel{
+		mockMessageEditor: mockMessageEditor{},
+		streamer: &mockStreamer{
+			finalizeFn: func(_ context.Context, content string) error {
+				if content != "final reply" {
+					t.Fatalf("unexpected finalize content: %q", content)
+				}
+				return nil
+			},
+		},
+	}
+	m.channels["test"] = ch
+
+	streamer, ok := m.GetStreamer(context.Background(), "test", "123")
+	if !ok {
+		t.Fatal("expected streamer to be available")
+	}
+	if err := streamer.Finalize(context.Background(), "final reply"); err != nil {
+		t.Fatalf("Finalize() error = %v", err)
+	}
+	if ch.clearedChatID != "123" {
+		t.Fatalf("expected tracked tool feedback to be cleared for chat 123, got %q", ch.clearedChatID)
+	}
+	if ch.dismissedChatID != "" {
+		t.Fatalf("expected tracked tool feedback message to be preserved, got dismissal for %q", ch.dismissedChatID)
+	}
+	if _, ok := m.streamActive.Load("test:123"); !ok {
+		t.Fatal("expected streamActive marker to be recorded after finalize")
+	}
+}
+
 func TestGetStreamer_FinalizeDismissesResolvedTrackedToolFeedback(t *testing.T) {
 	m := newTestManager()
 	ch := &mockStreamingChannel{

pkg/channels/pico/client_test.go

@@ -333,18 +333,33 @@ func TestIsThoughtPayload(t *testing.T) {
 		want    bool
 	}{
 		{
-			name:    "explicit thought bool",
+			name:    "explicit thought kind",
+			payload: map[string]any{PayloadKeyKind: MessageKindThought},
+			want:    true,
+		},
+		{
+			name:    "thought kind ignores case and whitespace",
+			payload: map[string]any{PayloadKeyKind: "  ThOuGhT  "},
+			want:    true,
+		},
+		{
+			name:    "legacy thought bool remains supported for inbound compatibility",
 			payload: map[string]any{PayloadKeyThought: true},
 			want:    true,
 		},
 		{
-			name:    "thought false",
+			name:    "legacy thought false",
 			payload: map[string]any{PayloadKeyThought: false},
 			want:    false,
 		},
 		{
-			name:    "thought string ignored",
-			payload: map[string]any{PayloadKeyThought: "true"},
+			name:    "tool calls kind",
+			payload: map[string]any{PayloadKeyKind: MessageKindToolCalls},
+			want:    false,
+		},
+		{
+			name:    "non-string kind ignored",
+			payload: map[string]any{PayloadKeyKind: true},
 			want:    false,
 		},
 		{
@@ -380,7 +395,7 @@ func TestPicoClientChannel_HandleServerMessage_IgnoresThought(t *testing.T) {
 		Type: TypeMessageCreate,
 		Payload: map[string]any{
 			PayloadKeyContent: "internal reasoning",
-			PayloadKeyThought: true,
+			PayloadKeyKind:    MessageKindThought,
 		},
 	})
 
@@ -390,3 +405,31 @@ func TestPicoClientChannel_HandleServerMessage_IgnoresThought(t *testing.T) {
 	case <-time.After(150 * time.Millisecond):
 	}
 }
+
+func TestPicoClientChannel_HandleServerMessage_IgnoresLegacyThoughtBool(t *testing.T) {
+	mb := bus.NewMessageBus()
+	bc := &config.Channel{Type: config.ChannelPicoClient, Enabled: true}
+	ch, err := NewPicoClientChannel(bc, &config.PicoClientSettings{
+		URL: "ws://localhost:8080/ws",
+	}, mb)
+	if err != nil {
+		t.Fatalf("NewPicoClientChannel() error = %v", err)
+	}
+
+	ch.ctx = context.Background()
+	pc := &picoConn{sessionID: "sess-thought-legacy"}
+
+	ch.handleServerMessage(pc, PicoMessage{
+		Type: TypeMessageCreate,
+		Payload: map[string]any{
+			PayloadKeyContent: "legacy internal reasoning",
+			PayloadKeyThought: true,
+		},
+	})
+
+	select {
+	case msg := <-mb.InboundChan():
+		t.Fatalf("expected no inbound publish for legacy thought payload, got %+v", msg)
+	case <-time.After(150 * time.Millisecond):
+	}
+}

pkg/channels/pico/pico.go

@@ -23,6 +23,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/identity"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 // picoConn represents a single WebSocket connection.
@@ -57,8 +58,17 @@ func outboundMessageIsToolFeedback(msg bus.OutboundMessage) bool {
 	return strings.EqualFold(strings.TrimSpace(msg.Context.Raw["message_kind"]), "tool_feedback")
 }
 
+func outboundMessageIsToolCalls(msg bus.OutboundMessage) bool {
+	if len(msg.Context.Raw) == 0 {
+		return false
+	}
+	return strings.EqualFold(strings.TrimSpace(msg.Context.Raw["message_kind"]), MessageKindToolCalls)
+}
+
 func outboundMessageFinalizesTrackedToolFeedback(msg bus.OutboundMessage) bool {
-	return !outboundMessageIsToolFeedback(msg) && !outboundMessageIsThought(msg)
+	return !outboundMessageIsToolFeedback(msg) &&
+		!outboundMessageIsThought(msg) &&
+		!outboundMessageIsToolCalls(msg)
 }
 
 // writeJSON sends a JSON message to the connection with write locking.
@@ -289,6 +299,7 @@ func (c *PicoChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]stri
 	}
 	isThought := outboundMessageIsThought(msg)
 	isToolFeedback := outboundMessageIsToolFeedback(msg)
+	isToolCalls := outboundMessageIsToolCalls(msg)
 	if isToolFeedback {
 		if msgID, handled, err := c.progress.Update(ctx, msg.ChatID, msg.Content); handled {
 			if err != nil {
@@ -312,9 +323,23 @@ func (c *PicoChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]stri
 
 	payload := map[string]any{
 		PayloadKeyContent: content,
-		PayloadKeyThought: isThought,
 		"message_id":      msgID,
 	}
+	switch {
+	case isThought:
+		payload[PayloadKeyKind] = MessageKindThought
+
+		// This field is kept solely for compatibility with legacy pico clients that
+		// do not yet support the newer "kind" field.
+		// DO NOT use it for any purpose other than legacy client compatibility.
+		payload[PayloadKeyThought] = true
+
+	case isToolCalls:
+		payload[PayloadKeyKind] = MessageKindToolCalls
+		if toolCalls, ok := picoToolCallsPayload(msg); ok {
+			payload[PayloadKeyToolCalls] = toolCalls
+		}
+	}
 	setContextUsagePayload(payload, msg.ContextUsage)
 	outMsg := newMessage(TypeMessageCreate, payload)
 
@@ -440,7 +465,6 @@ func (c *PicoChannel) SendPlaceholder(ctx context.Context, chatID string) (strin
 	msgID := uuid.New().String()
 	outMsg := newMessage(TypeMessageCreate, map[string]any{
 		PayloadKeyContent: text,
-		PayloadKeyThought: false,
 		"message_id":      msgID,
 	})
 
@@ -1070,6 +1094,19 @@ func setContextUsagePayload(payload map[string]any, u *bus.ContextUsage) {
 	}
 }
 
+func picoToolCallsPayload(msg bus.OutboundMessage) ([]utils.VisibleToolCall, bool) {
+	raw := strings.TrimSpace(msg.Context.Raw[PayloadKeyToolCalls])
+	if raw == "" {
+		return nil, false
+	}
+
+	var toolCalls []utils.VisibleToolCall
+	if err := json.Unmarshal([]byte(raw), &toolCalls); err != nil || len(toolCalls) == 0 {
+		return nil, false
+	}
+	return toolCalls, true
+}
+
 func (c *PicoChannel) editMessage(
 	ctx context.Context,
 	chatID string,

pkg/channels/pico/pico_test.go

@@ -131,8 +131,8 @@ func TestSend_ThoughtMessageDoesNotFinalizeTrackedToolFeedback(t *testing.T) {
 		if got := payload[PayloadKeyContent]; got != "thinking trace" {
 			t.Fatalf("thought content = %#v, want %q", got, "thinking trace")
 		}
-		if got := payload[PayloadKeyThought]; got != true {
-			t.Fatalf("thought flag = %#v, want true", got)
+		if got := payload[PayloadKeyKind]; got != MessageKindThought {
+			t.Fatalf("thought kind = %#v, want %q", got, MessageKindThought)
 		}
 		if got := payload["message_id"]; got == "msg-progress" || got == nil || got == "" {
 			t.Fatalf("thought message_id = %#v, want new non-progress id", got)
@@ -193,6 +193,47 @@ func TestSend_ThoughtMessageDoesNotFinalizeTrackedToolFeedback(t *testing.T) {
 	}
 }
 
+func TestSendPlaceholder_EmitsNormalMessageWithoutKind(t *testing.T) {
+	ch := newTestPicoChannel(t)
+	ch.bc.Placeholder.Enabled = true
+
+	if err := ch.Start(context.Background()); err != nil {
+		t.Fatalf("Start() error = %v", err)
+	}
+	defer ch.Stop(context.Background())
+
+	clientConn, received, cleanup := newTestPicoWebSocket(t)
+	defer cleanup()
+	ch.addConnForTest(&picoConn{id: "conn-1", conn: clientConn, sessionID: "sess-1"})
+
+	msgID, err := ch.SendPlaceholder(context.Background(), "pico:sess-1")
+	if err != nil {
+		t.Fatalf("SendPlaceholder() error = %v", err)
+	}
+	if msgID == "" {
+		t.Fatal("expected placeholder message id")
+	}
+
+	select {
+	case msg := <-received:
+		if msg.Type != TypeMessageCreate {
+			t.Fatalf("placeholder message type = %q, want %q", msg.Type, TypeMessageCreate)
+		}
+		payload := msg.Payload
+		if got := payload["message_id"]; got != msgID {
+			t.Fatalf("placeholder message_id = %#v, want %q", got, msgID)
+		}
+		if got := payload[PayloadKeyContent]; got != "Thinking..." {
+			t.Fatalf("placeholder content = %#v, want %q", got, "Thinking...")
+		}
+		if got, ok := payload[PayloadKeyKind]; ok {
+			t.Fatalf("placeholder kind = %#v, want absent", got)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("expected placeholder message to be delivered")
+	}
+}
+
 func TestCreateAndAddConnection_RespectsMaxConnectionsConcurrently(t *testing.T) {
 	ch := newTestPicoChannel(t)