From d8c5183d9a9b2577a9099f451074d2e010f6843c Mon Sep 17 00:00:00 2001
From: Mauro <afjcjsbx@gmail.com>
Date: Fri, 3 Apr 2026 19:30:36 +0200
Subject: [PATCH 01/25] feat(mcp): store oversized text results as artifacts
 (#2308)

* feat(mcp): store oversized text results as artifacts

* feat(mcp): fix doc

* fix(mcp): preserve raw MCP payload in text artifacts

* fix(mcp): avoid leaking large text when artifact persistence fails

* chore(mcp): clarify inline text limit and cover artifact edge cases
---
 docs/tools_configuration.md |   3 +
 pkg/agent/loop_mcp.go       |   2 +
 pkg/config/config.go        |  11 +++
 pkg/config/config_test.go   |  35 ++++++++
 pkg/config/defaults.go      |   3 +-
 pkg/tools/mcp_tool.go       | 133 +++++++++++++++++++++++----
 pkg/tools/mcp_tool_test.go  | 174 ++++++++++++++++++++++++++++++++++++
 7 files changed, 342 insertions(+), 19 deletions(-)

diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md
index 5a4b5bb28..adee9244a 100644
--- a/docs/tools_configuration.md
+++ b/docs/tools_configuration.md
@@ -528,6 +528,9 @@ For example:
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
+- `PICOCLAW_TOOLS_MCP_MAX_INLINE_TEXT_CHARS=16384`
 
 Note: Nested map-style config (for example `tools.mcp.servers.<name>.*`) is configured in `config.json` rather than
 environment variables.
+
+For MCP tools, `tools.mcp.max_inline_text_chars` controls how much text result is kept inline in model context. The threshold is counted in Unicode characters (Go runes), not bytes. For example, `16384` means up to 16,384 characters inline, which may occupy more than 16 KB for multibyte text such as CJK. Above this threshold, PicoClaw saves the MCP text result as a local artifact in the agent workspace and gives the model a short note plus a structured `[file:...]` artifact path instead of injecting the full payload into context.
diff --git a/pkg/agent/loop_mcp.go b/pkg/agent/loop_mcp.go
index 97debbc33..b9c844d1a 100644
--- a/pkg/agent/loop_mcp.go
+++ b/pkg/agent/loop_mcp.go
@@ -126,6 +126,8 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
 					}
 
 					mcpTool := tools.NewMCPTool(mcpManager, serverName, tool)
+					mcpTool.SetWorkspace(agent.Workspace)
+					mcpTool.SetMaxInlineTextRunes(al.cfg.Tools.MCP.GetMaxInlineTextChars())
 
 					if registerAsHidden {
 						agent.Tools.RegisterHidden(mcpTool)
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 85623cbc4..7165246e5 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -943,10 +943,21 @@ type MCPServerConfig struct {
 type MCPConfig struct {
 	ToolConfig `                    envPrefix:"PICOCLAW_TOOLS_MCP_"`
 	Discovery  ToolDiscoveryConfig `                                json:"discovery"`
+	// MaxInlineTextChars controls how much MCP text stays inline before it is saved as an artifact.
+	MaxInlineTextChars int `json:"max_inline_text_chars,omitempty" env:"PICOCLAW_TOOLS_MCP_MAX_INLINE_TEXT_CHARS"`
 	// Servers is a map of server name to server configuration
 	Servers map[string]MCPServerConfig `json:"servers,omitempty"`
 }
 
+const DefaultMCPMaxInlineTextChars = 16 * 1024
+
+func (c *MCPConfig) GetMaxInlineTextChars() int {
+	if c.MaxInlineTextChars > 0 {
+		return c.MaxInlineTextChars
+	}
+	return DefaultMCPMaxInlineTextChars
+}
+
 func LoadConfig(path string) (*Config, error) {
 	logger.Debugf("loading config from %s", path)
 
diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go
index a1410f940..8e58a684e 100644
--- a/pkg/config/config_test.go
+++ b/pkg/config/config_test.go
@@ -198,6 +198,41 @@ func TestAgentConfig_FullParse(t *testing.T) {
 	}
 }
 
+func TestDefaultConfig_MCPMaxInlineTextChars(t *testing.T) {
+	cfg := DefaultConfig()
+	if cfg.Tools.MCP.GetMaxInlineTextChars() != DefaultMCPMaxInlineTextChars {
+		t.Fatalf(
+			"DefaultConfig().Tools.MCP.GetMaxInlineTextChars() = %d, want %d",
+			cfg.Tools.MCP.GetMaxInlineTextChars(),
+			DefaultMCPMaxInlineTextChars,
+		)
+	}
+}
+
+func TestLoadConfig_MCPMaxInlineTextChars(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.json")
+	raw := `{
+		"tools": {
+			"mcp": {
+				"enabled": true,
+				"max_inline_text_chars": 2048
+			}
+		}
+	}`
+	if err := os.WriteFile(configPath, []byte(raw), 0o644); err != nil {
+		t.Fatalf("WriteFile(configPath): %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error: %v", err)
+	}
+	if got := cfg.Tools.MCP.GetMaxInlineTextChars(); got != 2048 {
+		t.Fatalf("cfg.Tools.MCP.GetMaxInlineTextChars() = %d, want 2048", got)
+	}
+}
+
 func TestConfig_BackwardCompat_NoAgentsList(t *testing.T) {
 	jsonData := `{
 		"agents": {
diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go
index 39cdb89e6..c2e1a31f3 100644
--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@@ -462,7 +462,8 @@ func DefaultConfig() *Config {
 					UseBM25:          true,
 					UseRegex:         false,
 				},
-				Servers: map[string]MCPServerConfig{},
+				MaxInlineTextChars: DefaultMCPMaxInlineTextChars,
+				Servers:            map[string]MCPServerConfig{},
 			},
 			AppendFile: ToolConfig{
 				Enabled: true,
diff --git a/pkg/tools/mcp_tool.go b/pkg/tools/mcp_tool.go
index 5bffb4e89..1caf390cf 100644
--- a/pkg/tools/mcp_tool.go
+++ b/pkg/tools/mcp_tool.go
@@ -6,11 +6,14 @@ import (
 	"fmt"
 	"hash/fnv"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
+	"unicode/utf8"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 
+	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/media"
 )
 
@@ -26,18 +29,21 @@ type MCPManager interface {
 
 // MCPTool wraps an MCP tool to implement the Tool interface
 type MCPTool struct {
-	manager    MCPManager
-	serverName string
-	tool       *mcp.Tool
-	mediaStore media.MediaStore
+	manager            MCPManager
+	serverName         string
+	tool               *mcp.Tool
+	mediaStore         media.MediaStore
+	workspace          string
+	maxInlineTextRunes int
 }
 
 // NewMCPTool creates a new MCP tool wrapper
 func NewMCPTool(manager MCPManager, serverName string, tool *mcp.Tool) *MCPTool {
 	return &MCPTool{
-		manager:    manager,
-		serverName: serverName,
-		tool:       tool,
+		manager:            manager,
+		serverName:         serverName,
+		tool:               tool,
+		maxInlineTextRunes: maxMCPInlineTextRunes,
 	}
 }
 
@@ -45,6 +51,18 @@ func (t *MCPTool) SetMediaStore(store media.MediaStore) {
 	t.mediaStore = store
 }
 
+func (t *MCPTool) SetWorkspace(workspace string) {
+	t.workspace = strings.TrimSpace(workspace)
+}
+
+func (t *MCPTool) SetMaxInlineTextRunes(limit int) {
+	if limit > 0 {
+		t.maxInlineTextRunes = limit
+	}
+}
+
+const maxMCPInlineTextRunes = 16 * 1024
+
 // sanitizeIdentifierComponent normalizes a string so it can be safely used
 // as part of a tool/function identifier for downstream providers.
 // It:
@@ -255,14 +273,19 @@ func extractContentText(content []mcp.Content) string {
 
 func (t *MCPTool) normalizeResultContent(ctx context.Context, content []mcp.Content) *ToolResult {
 	llmParts := make([]string, 0, len(content))
+	rawTextParts := make([]string, 0, len(content))
 	mediaRefs := make([]string, 0, len(content))
 
 	for _, c := range content {
 		switch v := c.(type) {
 		case *mcp.TextContent:
-			text := strings.TrimSpace(sanitizeToolLLMContent(v.Text))
-			if text != "" {
-				llmParts = append(llmParts, text)
+			rawText := strings.TrimSpace(v.Text)
+			if rawText != "" {
+				rawTextParts = append(rawTextParts, rawText)
+			}
+			safeText := strings.TrimSpace(sanitizeToolLLMContent(v.Text))
+			if safeText != "" {
+				llmParts = append(llmParts, safeText)
 			}
 		case *mcp.ImageContent:
 			ref, note := t.storeBinaryContent(
@@ -295,10 +318,13 @@ func (t *MCPTool) normalizeResultContent(ctx context.Context, content []mcp.Cont
 		case *mcp.ResourceLink:
 			llmParts = append(llmParts, summarizeResourceLink(v))
 		case *mcp.EmbeddedResource:
-			ref, note := t.storeEmbeddedResource(ctx, v)
+			ref, note, rawText := t.storeEmbeddedResource(ctx, v)
 			if ref != "" {
 				mediaRefs = append(mediaRefs, ref)
 			}
+			if rawText != "" {
+				rawTextParts = append(rawTextParts, rawText)
+			}
 			if note != "" {
 				llmParts = append(llmParts, note)
 			}
@@ -307,34 +333,105 @@ func (t *MCPTool) normalizeResultContent(ctx context.Context, content []mcp.Cont
 		}
 	}
 
+	forLLM := strings.Join(compactStrings(llmParts), "\n")
+	rawText := strings.Join(compactStrings(rawTextParts), "\n")
+	if artifactResult := t.persistLargeTextArtifact(rawText); artifactResult != nil {
+		artifactResult.Media = mediaRefs
+		return artifactResult
+	}
+
 	result := &ToolResult{
-		ForLLM: strings.Join(compactStrings(llmParts), "\n"),
+		ForLLM: forLLM,
 		Media:  mediaRefs,
 	}
 	return result
 }
 
-func (t *MCPTool) storeEmbeddedResource(ctx context.Context, content *mcp.EmbeddedResource) (string, string) {
+func (t *MCPTool) persistLargeTextArtifact(text string) *ToolResult {
+	text = strings.TrimSpace(text)
+	limit := t.maxInlineTextRunes
+	if limit <= 0 {
+		limit = maxMCPInlineTextRunes
+	}
+	size := utf8.RuneCountInString(text)
+	if text == "" || size <= limit || t.workspace == "" {
+		return nil
+	}
+
+	dir := filepath.Join(t.workspace, ".artifacts", "mcp")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return t.largeTextArtifactFallback(text, err)
+	}
+	// TODO: Add lifecycle cleanup/retention for MCP artifact files.
+
+	pattern := fmt.Sprintf(
+		"%s_%s_*.txt",
+		sanitizeIdentifierComponent(t.serverName),
+		sanitizeIdentifierComponent(t.tool.Name),
+	)
+	tmpFile, err := os.CreateTemp(dir, pattern)
+	if err != nil {
+		return t.largeTextArtifactFallback(text, err)
+	}
+	path := tmpFile.Name()
+	if _, err = tmpFile.WriteString(text); err != nil {
+		_ = tmpFile.Close()
+		_ = os.Remove(path)
+		return t.largeTextArtifactFallback(text, err)
+	}
+	if err = tmpFile.Close(); err != nil {
+		_ = os.Remove(path)
+		return t.largeTextArtifactFallback(text, err)
+	}
+
+	return &ToolResult{
+		ForLLM: fmt.Sprintf(
+			"[MCP returned a large text result (%d chars); omitted from model context and saved as a local artifact.]",
+			size,
+		),
+		ArtifactTags: []string{"[file:" + path + "]"},
+	}
+}
+
+func (t *MCPTool) largeTextArtifactFallback(text string, err error) *ToolResult {
+	size := utf8.RuneCountInString(text)
+	logger.WarnCF("tool", "Failed to persist large MCP text artifact", map[string]any{
+		"server": t.serverName,
+		"tool":   t.tool.Name,
+		"chars":  size,
+		"error":  err.Error(),
+	})
+	return &ToolResult{
+		ForLLM: fmt.Sprintf(
+			"[MCP returned a large text result (%d chars); omitted from model context because artifact persistence failed.]",
+			size,
+		),
+	}
+}
+
+func (t *MCPTool) storeEmbeddedResource(ctx context.Context, content *mcp.EmbeddedResource) (string, string, string) {
 	if content == nil || content.Resource == nil {
-		return "", "[MCP returned an embedded resource without data.]"
+		return "", "[MCP returned an embedded resource without data.]", ""
 	}
 
 	resource := content.Resource
 	if len(resource.Blob) > 0 {
-		return t.storeBinaryContent(
+		ref, note := t.storeBinaryContent(
 			ctx,
 			"resource",
 			normalizedMIMEType(resource.MIMEType),
 			resource.Blob,
 			content.Annotations,
 		)
+		return ref, note, ""
 	}
 
-	if strings.TrimSpace(resource.Text) != "" {
-		return "", sanitizeToolLLMContent(resource.Text)
+	rawText := strings.TrimSpace(resource.Text)
+	if rawText != "" {
+		return "", sanitizeToolLLMContent(resource.Text), rawText
 	}
 
-	return "", summarizeEmbeddedResource(content)
+	return "", summarizeEmbeddedResource(content), ""
 }
 
 func (t *MCPTool) storeBinaryContent(
diff --git a/pkg/tools/mcp_tool_test.go b/pkg/tools/mcp_tool_test.go
index 8bbac3bc7..f2b02d6f6 100644
--- a/pkg/tools/mcp_tool_test.go
+++ b/pkg/tools/mcp_tool_test.go
@@ -634,3 +634,177 @@ func TestMCPTool_Execute_LargeBase64TextIsOmittedFromContext(t *testing.T) {
 		t.Fatalf("expected sanitized large base64 note, got %q", result.ForLLM)
 	}
 }
+
+func TestMCPTool_Execute_LargeBase64TextArtifactPreservesRawPayload(t *testing.T) {
+	workspace := t.TempDir()
+	largeBase64 := strings.Repeat("QUJD", 400)
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: largeBase64},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "test_server", &mcp.Tool{Name: "dump_payload"})
+	mcpTool.SetWorkspace(workspace)
+	mcpTool.SetMaxInlineTextRunes(32)
+
+	result := mcpTool.Execute(context.Background(), nil)
+
+	if !strings.Contains(result.ForLLM, "saved as a local artifact") {
+		t.Fatalf("expected artifact note, got %q", result.ForLLM)
+	}
+	if result.ForLLM == largeBase64OmittedMessage {
+		t.Fatalf("expected artifact note instead of sanitized base64 placeholder")
+	}
+	if len(result.ArtifactTags) != 1 {
+		t.Fatalf("expected 1 artifact tag, got %d", len(result.ArtifactTags))
+	}
+	tag := result.ArtifactTags[0]
+	const prefix = "[file:"
+	if !strings.HasPrefix(tag, prefix) || !strings.HasSuffix(tag, "]") {
+		t.Fatalf("expected file artifact tag, got %q", tag)
+	}
+	path := strings.TrimSuffix(strings.TrimPrefix(tag, prefix), "]")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("expected artifact file to be readable: %v", err)
+	}
+	if string(data) != largeBase64 {
+		t.Fatalf("expected artifact file contents to preserve raw MCP payload")
+	}
+}
+
+func TestMCPTool_Execute_LargeTextStoredAsArtifact(t *testing.T) {
+	workspace := t.TempDir()
+	largeText := strings.Repeat("This is a large MCP text payload.\n", 800)
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: largeText},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "test_server", &mcp.Tool{Name: "dump_payload"})
+	mcpTool.SetWorkspace(workspace)
+
+	result := mcpTool.Execute(context.Background(), nil)
+
+	if strings.Contains(result.ForLLM, "This is a large MCP text payload") {
+		t.Fatalf("expected large MCP text to be omitted from ForLLM, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "saved as a local artifact") {
+		t.Fatalf("expected artifact note, got %q", result.ForLLM)
+	}
+	if len(result.ArtifactTags) != 1 {
+		t.Fatalf("expected 1 artifact tag, got %d", len(result.ArtifactTags))
+	}
+	tag := result.ArtifactTags[0]
+	const prefix = "[file:"
+	if !strings.HasPrefix(tag, prefix) || !strings.HasSuffix(tag, "]") {
+		t.Fatalf("expected file artifact tag, got %q", tag)
+	}
+	path := strings.TrimSuffix(strings.TrimPrefix(tag, prefix), "]")
+	if !strings.HasPrefix(path, workspace) {
+		t.Fatalf("expected artifact inside workspace, got %q", path)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("expected artifact file to be readable: %v", err)
+	}
+	if string(data) != strings.TrimSpace(largeText) {
+		t.Fatalf("expected artifact file contents to match source text")
+	}
+}
+
+func TestMCPTool_Execute_CustomInlineTextThreshold(t *testing.T) {
+	workspace := t.TempDir()
+	text := strings.Repeat("small custom threshold text\n", 20)
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: text},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "test_server", &mcp.Tool{Name: "dump_payload"})
+	mcpTool.SetWorkspace(workspace)
+	mcpTool.SetMaxInlineTextRunes(32)
+
+	result := mcpTool.Execute(context.Background(), nil)
+
+	if len(result.ArtifactTags) != 1 {
+		t.Fatalf("expected custom threshold to persist artifact, got %+v", result)
+	}
+	if strings.Contains(result.ForLLM, "small custom threshold text") {
+		t.Fatalf("expected text to be omitted from ForLLM, got %q", result.ForLLM)
+	}
+}
+
+func TestMCPTool_Execute_LargeTextArtifactFailureStillOmitsContext(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	workspaceFile := filepath.Join(workspaceRoot, "not-a-directory")
+	if err := os.WriteFile(workspaceFile, []byte("x"), 0o600); err != nil {
+		t.Fatalf("failed to create workspace file: %v", err)
+	}
+
+	largeText := strings.Repeat("This is a large MCP text payload.\n", 800)
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: largeText},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "test_server", &mcp.Tool{Name: "dump_payload"})
+	mcpTool.SetWorkspace(workspaceFile)
+
+	result := mcpTool.Execute(context.Background(), nil)
+
+	if strings.Contains(result.ForLLM, "This is a large MCP text payload") {
+		t.Fatalf("expected large MCP text to be omitted from ForLLM, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "artifact persistence failed") {
+		t.Fatalf("expected persistence failure note, got %q", result.ForLLM)
+	}
+	if len(result.ArtifactTags) != 0 {
+		t.Fatalf("expected no artifact tags on persistence failure, got %+v", result.ArtifactTags)
+	}
+}
+
+func TestMCPTool_Execute_WhitespaceWorkspaceDisablesArtifactPersistence(t *testing.T) {
+	largeText := strings.Repeat("This is a large MCP text payload.\n", 800)
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: largeText},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "test_server", &mcp.Tool{Name: "dump_payload"})
+	mcpTool.SetWorkspace(" \n\t ")
+
+	result := mcpTool.Execute(context.Background(), nil)
+
+	if len(result.ArtifactTags) != 0 {
+		t.Fatalf("expected no artifact tags for whitespace workspace, got %+v", result.ArtifactTags)
+	}
+	if !strings.Contains(result.ForLLM, "This is a large MCP text payload") {
+		t.Fatalf("expected large text to remain inline when workspace is blank, got %q", result.ForLLM)
+	}
+}

From 8d954490846ff480f20e9c6d1c9d93039fa06c77 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Tue, 24 Mar 2026 09:05:24 +0100
Subject: [PATCH 02/25] added two new providers: NVIDIA and Azure plus Security
 enhancments to lock down skills if desired and added a configurable chat API

---
 logs/gateway.log                             |  2 +
 logs/gateway_panic.log                       | 26 ++++++
 pkg/agent/loop.go                            | 12 +--
 pkg/agent/loop_mcp.go                        |  2 +-
 pkg/agent/steering.go                        |  2 +-
 pkg/config/config.go                         | 38 +++++++-
 pkg/config/defaults.go                       | 10 ++-
 pkg/config/gateway.go                        | 11 ++-
 pkg/gateway/gateway.go                       | 12 +++
 pkg/health/server.go                         | 91 ++++++++++++++++++++
 pkg/providers/http_provider.go               | 17 ++++
 pkg/providers/openai_compat/provider.go      |  7 +-
 pkg/providers/openai_compat/provider_test.go |  6 +-
 pkg/skills/loader.go                         | 54 ++++++++++--
 pkg/skills/loader_test.go                    | 60 +++++++++++--
 pkg/tools/registry.go                        | 37 +++++---
 pkg/tools/skills_install.go                  | 29 +++++--
 pkg/tools/skills_install_test.go             | 61 +++++++++++--
 pkg/tools/skills_search.go                   | 22 ++++-
 pkg/tools/skills_search_test.go              | 12 +--
 workspace/HEARTBEAT.md                       | 22 +++++
 workspace/cron/jobs.json                     |  4 +
 workspace/heartbeat.log                      |  1 +
 workspace/state/state.json                   |  4 +
 24 files changed, 472 insertions(+), 70 deletions(-)
 create mode 100644 logs/gateway.log
 create mode 100644 logs/gateway_panic.log
 create mode 100644 workspace/HEARTBEAT.md
 create mode 100644 workspace/cron/jobs.json
 create mode 100644 workspace/heartbeat.log
 create mode 100644 workspace/state/state.json

diff --git a/logs/gateway.log b/logs/gateway.log
new file mode 100644
index 000000000..770d23f8b
--- /dev/null
+++ b/logs/gateway.log
@@ -0,0 +1,2 @@
+{"level":"warn","path":"/home/stevef/dev/tomerge/github/picoclaw/config.json","time":"2026-03-24T08:13:49+01:00","caller":"/home/stevef/dev/tomerge/github/picoclaw/pkg/config/config.go:1363","message":"config file not found, using default config"}
+{"level":"warn","path":"/home/stevef/dev/tomerge/github/picoclaw/config.json","time":"2026-03-24T08:15:23+01:00","caller":"/home/stevef/dev/tomerge/github/picoclaw/pkg/config/config.go:1363","message":"config file not found, using default config"}
diff --git a/logs/gateway_panic.log b/logs/gateway_panic.log
new file mode 100644
index 000000000..67e98bfaf
--- /dev/null
+++ b/logs/gateway_panic.log
@@ -0,0 +1,26 @@
+Error: error creating provider: model "" not found in model_list: model "" not found in model_list or providers
+Usage:
+  picoclaw gateway [flags]
+
+Aliases:
+  gateway, g
+
+Flags:
+  -E, --allow-empty   Continue starting even when no default model is configured
+  -d, --debug         Enable debug logging
+  -h, --help          help for gateway
+  -T, --no-truncate   Disable string truncation in debug logs
+
+Error: error creating provider: model "" not found in model_list: model "" not found in model_list or providers
+Usage:
+  picoclaw gateway [flags]
+
+Aliases:
+  gateway, g
+
+Flags:
+  -E, --allow-empty   Continue starting even when no default model is configured
+  -d, --debug         Enable debug logging
+  -h, --help          help for gateway
+  -T, --no-truncate   Disable string truncation in debug logs
+
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index 808d12c07..a54dbffbe 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -327,11 +327,11 @@ func registerSharedTools(
 					cfg.Tools.Skills.SearchCache.MaxSize,
 					time.Duration(cfg.Tools.Skills.SearchCache.TTLSeconds)*time.Second,
 				)
-				agent.Tools.Register(tools.NewFindSkillsTool(registryMgr, searchCache))
+				agent.Tools.Register(tools.NewFindSkillsTool(registryMgr, searchCache, cfg.Tools.Skills.Whitelist, cfg.Tools.Skills.WhitelistEnabled))
 			}
 
 			if install_skills_enable {
-				agent.Tools.Register(tools.NewInstallSkillTool(registryMgr, agent.Workspace))
+				agent.Tools.Register(tools.NewInstallSkillTool(registryMgr, agent.Workspace, cfg.Tools.Skills.Whitelist, cfg.Tools.Skills.WhitelistEnabled))
 			}
 		}
 
@@ -437,6 +437,8 @@ func registerSharedTools(
 		} else if (spawnEnabled || spawnStatusEnabled) && !cfg.Tools.IsToolEnabled("subagent") {
 			logger.WarnCF("agent", "spawn/spawn_status tools require subagent to be enabled", nil)
 		}
+		// Apply global tools whitelist
+		agent.Tools.Filter(cfg.Tools.Whitelist, cfg.Tools.WhitelistEnabled)
 	}
 }
 
@@ -446,7 +448,7 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 	if err := al.ensureHooksInitialized(ctx); err != nil {
 		return err
 	}
-	if err := al.ensureMCPInitialized(ctx); err != nil {
+	if err := al.EnsureMCPInitialized(ctx); err != nil {
 		return err
 	}
 
@@ -1293,7 +1295,7 @@ func (al *AgentLoop) ProcessDirectWithChannel(
 	if err := al.ensureHooksInitialized(ctx); err != nil {
 		return "", err
 	}
-	if err := al.ensureMCPInitialized(ctx); err != nil {
+	if err := al.EnsureMCPInitialized(ctx); err != nil {
 		return "", err
 	}
 
@@ -1317,7 +1319,7 @@ func (al *AgentLoop) ProcessHeartbeat(
 	if err := al.ensureHooksInitialized(ctx); err != nil {
 		return "", err
 	}
-	if err := al.ensureMCPInitialized(ctx); err != nil {
+	if err := al.EnsureMCPInitialized(ctx); err != nil {
 		return "", err
 	}
 
diff --git a/pkg/agent/loop_mcp.go b/pkg/agent/loop_mcp.go
index b9c844d1a..e35609340 100644
--- a/pkg/agent/loop_mcp.go
+++ b/pkg/agent/loop_mcp.go
@@ -59,7 +59,7 @@ func (r *mcpRuntime) hasManager() bool {
 
 // ensureMCPInitialized loads MCP servers/tools once so both Run() and direct
 // agent mode share the same initialization path.
-func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
+func (al *AgentLoop) EnsureMCPInitialized(ctx context.Context) error {
 	if !al.cfg.Tools.IsToolEnabled("mcp") {
 		return nil
 	}
diff --git a/pkg/agent/steering.go b/pkg/agent/steering.go
index ad6613e8c..c8d66049b 100644
--- a/pkg/agent/steering.go
+++ b/pkg/agent/steering.go
@@ -332,7 +332,7 @@ func (al *AgentLoop) Continue(ctx context.Context, sessionKey, channel, chatID s
 	if err := al.ensureHooksInitialized(ctx); err != nil {
 		return "", err
 	}
-	if err := al.ensureMCPInitialized(ctx); err != nil {
+	if err := al.EnsureMCPInitialized(ctx); err != nil {
 		return "", err
 	}
 
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 7165246e5..5b88a0146 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -387,6 +387,10 @@ type DiscordConfig struct {
 	ReasoningChannelID string              `json:"reasoning_channel_id"    yaml:"-"               env:"PICOCLAW_CHANNELS_DISCORD_REASONING_CHANNEL_ID"`
 }
 
+func (c *DiscordConfig) SetToken(token string) {
+	c.Token = *NewSecureString(token)
+}
+
 type MaixCamConfig struct {
 	Enabled            bool                `json:"enabled"              env:"PICOCLAW_CHANNELS_MAIXCAM_ENABLED"`
 	Host               string              `json:"host"                 env:"PICOCLAW_CHANNELS_MAIXCAM_HOST"`
@@ -427,6 +431,14 @@ type SlackConfig struct {
 	ReasoningChannelID string              `json:"reasoning_channel_id"    yaml:"-"                   env:"PICOCLAW_CHANNELS_SLACK_REASONING_CHANNEL_ID"`
 }
 
+func (c *SlackConfig) SetBotToken(token string) {
+	c.BotToken = *NewSecureString(token)
+}
+
+func (c *SlackConfig) SetAppToken(token string) {
+	c.AppToken = *NewSecureString(token)
+}
+
 type MatrixConfig struct {
 	Enabled            bool                `json:"enabled"                        yaml:"-"                      env:"PICOCLAW_CHANNELS_MATRIX_ENABLED"`
 	Homeserver         string              `json:"homeserver"                     yaml:"-"                      env:"PICOCLAW_CHANNELS_MATRIX_HOMESERVER"`
@@ -625,6 +637,24 @@ type ModelConfig struct {
 	isVirtual bool
 }
 
+func (c *ModelConfig) UnmarshalJSON(data []byte) error {
+	type Alias ModelConfig
+	aux := &struct {
+		APIKey  string   `json:"api_key"`
+		APIKeys []string `json:"api_keys"`
+		*Alias
+	}{
+		Alias: (*Alias)(c),
+	}
+
+	if err := json.Unmarshal(data, aux); err != nil {
+		return err
+	}
+
+	c.APIKeys = toSecureStrings(mergeAPIKeys(aux.APIKey, aux.APIKeys))
+	return nil
+}
+
 // APIKey returns the first API key from apiKeys
 func (c *ModelConfig) APIKey() string {
 	if len(c.APIKeys) > 0 {
@@ -657,6 +687,8 @@ func (c *ModelConfig) SetAPIKey(value string) {
 	}
 }
 
+
+
 type ToolDiscoveryConfig struct {
 	Enabled          bool `json:"enabled"            env:"PICOCLAW_TOOLS_DISCOVERY_ENABLED"`
 	TTL              int  `json:"ttl"                env:"PICOCLAW_TOOLS_DISCOVERY_TTL"`
@@ -811,6 +843,8 @@ type SkillsToolsConfig struct {
 	Github                SkillsGithubConfig     `yaml:"github,omitempty"                                     json:"github"`
 	MaxConcurrentSearches int                    `yaml:"-"                                                    json:"max_concurrent_searches" env:"PICOCLAW_TOOLS_SKILLS_MAX_CONCURRENT_SEARCHES"`
 	SearchCache           SearchCacheConfig      `yaml:"-"                                                    json:"search_cache"`
+	Whitelist             FlexibleStringSlice    `json:"whitelist,omitempty"                                  env:"PICOCLAW_TOOLS_SKILLS_WHITELIST"`
+	WhitelistEnabled      bool                   `json:"whitelist_enabled,omitempty"                          env:"PICOCLAW_TOOLS_SKILLS_WHITELIST_ENABLED"`
 }
 
 type MediaCleanupConfig struct {
@@ -857,7 +891,9 @@ type ToolsConfig struct {
 	Exec            ExecConfig         `json:"exec"              yaml:"-"`
 	Skills          SkillsToolsConfig  `json:"skills"            yaml:"skills,omitempty"`
 	MediaCleanup    MediaCleanupConfig `json:"media_cleanup"     yaml:"-"`
-	MCP             MCPConfig          `json:"mcp"               yaml:"-"`
+	Whitelist        FlexibleStringSlice `json:"whitelist,omitempty"         yaml:"-" env:"PICOCLAW_TOOLS_WHITELIST"`
+	WhitelistEnabled bool                `json:"whitelist_enabled,omitempty" yaml:"-" env:"PICOCLAW_TOOLS_WHITELIST_ENABLED"`
+	MCP             MCPConfig          `json:"mcp"               yaml:"-""`
 	AppendFile      ToolConfig         `json:"append_file"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_APPEND_FILE_"`
 	EditFile        ToolConfig         `json:"edit_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_EDIT_FILE_"`
 	FindSkills      ToolConfig         `json:"find_skills"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_FIND_SKILLS_"`
diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go
index c2e1a31f3..bfda81c26 100644
--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@@ -358,11 +358,13 @@ func DefaultConfig() *Config {
 			},
 		},
 		Gateway: GatewayConfig{
-			Host:      "127.0.0.1",
-			Port:      18790,
-			HotReload: false,
-			LogLevel:  DefaultGatewayLogLevel,
+			Host:        "127.0.0.1",
+			Port:        18790,
+			ChatEnabled: true,
+			HotReload:   false,
+			LogLevel:    DefaultGatewayLogLevel,
 		},
+
 		Tools: ToolsConfig{
 			FilterSensitiveData: true,
 			FilterMinLength:     8,
diff --git a/pkg/config/gateway.go b/pkg/config/gateway.go
index e9f4085d3..30e6f4204 100644
--- a/pkg/config/gateway.go
+++ b/pkg/config/gateway.go
@@ -10,12 +10,15 @@ import (
 const DefaultGatewayLogLevel = "warn"
 
 type GatewayConfig struct {
-	Host      string `json:"host"                env:"PICOCLAW_GATEWAY_HOST"`
-	Port      int    `json:"port"                env:"PICOCLAW_GATEWAY_PORT"`
-	HotReload bool   `json:"hot_reload"          env:"PICOCLAW_GATEWAY_HOT_RELOAD"`
-	LogLevel  string `json:"log_level,omitempty" env:"PICOCLAW_LOG_LEVEL"`
+	Host        string `json:"host"                env:"PICOCLAW_GATEWAY_HOST"`
+	Port        int    `json:"port"                env:"PICOCLAW_GATEWAY_PORT"`
+	APIKey      string `json:"api_key"             env:"PICOCLAW_GATEWAY_API_KEY"`
+	ChatEnabled bool   `json:"chat_enabled"        env:"PICOCLAW_GATEWAY_CHAT_ENABLED"`
+	HotReload   bool   `json:"hot_reload"          env:"PICOCLAW_GATEWAY_HOT_RELOAD"`
+	LogLevel    string `json:"log_level,omitempty" env:"PICOCLAW_LOG_LEVEL"`
 }
 
+
 func canonicalGatewayLogLevel(level logger.LogLevel) string {
 	switch level {
 	case logger.DEBUG:
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
index 509b5d37e..6f6911122 100644
--- a/pkg/gateway/gateway.go
+++ b/pkg/gateway/gateway.go
@@ -203,8 +203,20 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 		}
 	}
 	runningServices.HealthServer.SetReloadFunc(reloadTrigger)
+	runningServices.HealthServer.SetAPIKey(cfg.Gateway.APIKey)
 	agentLoop.SetReloadFunc(reloadTrigger)
 
+	// Setup synchronous /chat endpoint handler
+	if cfg.Gateway.ChatEnabled {
+		runningServices.HealthServer.SetChatFunc(func(ctx context.Context, message, sessionID string) (string, error) {
+			if sessionID == "" {
+				sessionID = "http-chat"
+			}
+			return agentLoop.ProcessDirectWithChannel(ctx, message, sessionID, "http", "chat")
+		})
+	}
+
+
 	fmt.Printf("✓ Gateway started on %s:%d\n", cfg.Gateway.Host, cfg.Gateway.Port)
 	fmt.Println("Press Ctrl+C to stop")
 
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 2602cb965..16447a3c6 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -19,8 +19,11 @@ type Server struct {
 	startTime  time.Time
 	reloadFunc func() error
 	authToken  string // optional bearer token for protected endpoints
+	chatFunc   func(ctx context.Context, message, sessionID string) (string, error)
+	apiKey     string
 }
 
+
 type Check struct {
 	Name      string    `json:"name"`
 	Status    string    `json:"status"`
@@ -46,6 +49,8 @@ func NewServer(host string, port int, token string) *Server {
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
 	mux.HandleFunc("/reload", s.reloadHandler)
+	mux.HandleFunc("/chat", s.chatHandler)
+
 
 	addr := fmt.Sprintf("%s:%d", host, port)
 	s.server = &http.Server{
@@ -248,3 +253,89 @@ func extractBearerToken(header string) string {
 	}
 	return header[len(prefix):]
 }
+
+// SetChatFunc sets the callback that processes /chat requests.
+func (s *Server) SetChatFunc(fn func(ctx context.Context, message, sessionID string) (string, error)) {
+s.mu.Lock()
+defer s.mu.Unlock()
+s.chatFunc = fn
+}
+
+// SetAPIKey sets the expected X-API-Key header value.
+func (s *Server) SetAPIKey(key string) {
+s.mu.Lock()
+defer s.mu.Unlock()
+s.apiKey = key
+}
+
+func (s *Server) verifyAPIKey(r *http.Request) bool {
+s.mu.RLock()
+defer s.mu.RUnlock()
+if s.apiKey == "" {
+ true
+}
+return r.Header.Get("X-API-Key") == s.apiKey
+}
+
+// ChatRequest is the JSON body for POST /chat.
+type ChatRequest struct {
+Message   string `json:"message"`
+SessionID string `json:"session_id,omitempty"`
+}
+
+// ChatResponse is the JSON response from POST /chat.
+type ChatResponse struct {
+Response string `json:"response"`
+}
+
+func (s *Server) chatHandler(w http.ResponseWriter, r *http.Request) {
+if !s.verifyAPIKey(r) {
+tent-Type", "application/json")
+authorized)
+.NewEncoder(w).Encode(map[string]string{"error": "unauthorized"})
+
+}
+if r.Method != http.MethodPost {
+tent-Type", "application/json")
+otAllowed)
+.NewEncoder(w).Encode(map[string]string{"error": "method not allowed, use POST"})
+
+}
+
+s.mu.RLock()
+chatFunc := s.chatFunc
+s.mu.RUnlock()
+
+if chatFunc == nil {
+tent-Type", "application/json")
+available)
+.NewEncoder(w).Encode(map[string]string{"error": "chat not configured"})
+
+}
+
+var req ChatRequest
+if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+tent-Type", "application/json")
+uest)
+.NewEncoder(w).Encode(map[string]string{"error": "invalid JSON: " + err.Error()})
+
+}
+if req.Message == "" {
+tent-Type", "application/json")
+uest)
+.NewEncoder(w).Encode(map[string]string{"error": "message field is required"})
+
+}
+
+reply, err := chatFunc(r.Context(), req.Message, req.SessionID)
+if err != nil {
+tent-Type", "application/json")
+ternalServerError)
+.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
+
+}
+
+w.Header().Set("Content-Type", "application/json")
+w.WriteHeader(http.StatusOK)
+json.NewEncoder(w).Encode(ChatResponse{Response: reply})
+}
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index dae730536..b5cf0b8cd 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -45,6 +45,18 @@ func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
 	}
 }
 
+func NewAzureAIProvider(apiKey, apiBase, proxy string, requestTimeoutSeconds int) *HTTPProvider {
+	return &HTTPProvider{
+		delegate: openai_compat.NewProvider(
+			apiKey,
+			apiBase,
+			proxy,
+			openai_compat.WithAzureHeaders(),
+			openai_compat.WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+		),
+	}
+}
+
 func (p *HTTPProvider) Chat(
 	ctx context.Context,
 	messages []Message,
@@ -72,6 +84,11 @@ func (p *HTTPProvider) GetDefaultModel() string {
 	return ""
 }
 
+func (p *HTTPProvider) SetUseAzureHeaders(use bool) {
+	p.delegate.SetUseAzureHeaders(use)
+}
+
 func (p *HTTPProvider) SupportsNativeSearch() bool {
 	return p.delegate.SupportsNativeSearch()
 }
+
diff --git a/pkg/providers/openai_compat/provider.go b/pkg/providers/openai_compat/provider.go
index 7cda033ad..d4c3da2d9 100644
--- a/pkg/providers/openai_compat/provider.go
+++ b/pkg/providers/openai_compat/provider.go
@@ -57,10 +57,13 @@ var stripModelPrefixProviders = map[string]struct{}{
 	"mistral":    {},
 	"vivgrid":    {},
 	"minimax":    {},
-	"novita":     {},
-	"lmstudio":   {},
+	"novita":        {},
+	"lmstudio":      {},
+	"azure-ai":      {},
+	"azure-foundry": {},
 }
 
+
 func WithMaxTokensField(maxTokensField string) Option {
 	return func(p *Provider) {
 		p.maxTokensField = maxTokensField
diff --git a/pkg/providers/openai_compat/provider_test.go b/pkg/providers/openai_compat/provider_test.go
index 30aa76eb3..2ca8dd8c7 100644
--- a/pkg/providers/openai_compat/provider_test.go
+++ b/pkg/providers/openai_compat/provider_test.go
@@ -923,8 +923,8 @@ func TestSupportsPromptCacheKey(t *testing.T) {
 	}{
 		{"https://api.openai.com/v1", true},
 		{"https://api.openai.com/v1/", true},
-		{"https://myresource.openai.azure.com/openai/deployments/gpt-4", true},
-		{"https://eastus.openai.azure.com/v1", true},
+		{"https://myresource.openai.azure.com/openai/deployments/gpt-4", false},
+		{"https://eastus.openai.azure.com/v1", false},
 		{"https://api.mistral.ai/v1", false},
 		{"https://generativelanguage.googleapis.com/v1beta", false},
 		{"https://api.deepseek.com/v1", false},
@@ -995,7 +995,7 @@ func TestIsNativeSearchHost(t *testing.T) {
 		want    bool
 	}{
 		{"https://api.openai.com/v1", true},
-		{"https://myresource.openai.azure.com/openai/deployments/gpt-4", true},
+		{"https://myresource.openai.azure.com/openai/deployments/gpt-4", false},
 		{"https://api.mistral.ai/v1", false},
 		{"https://api.deepseek.com/v1", false},
 		{"https://api.groq.com/openai/v1", false},
diff --git a/pkg/skills/loader.go b/pkg/skills/loader.go
index f5985a662..d30018e45 100644
--- a/pkg/skills/loader.go
+++ b/pkg/skills/loader.go
@@ -63,6 +63,8 @@ type SkillsLoader struct {
 	workspaceSkills string // workspace skills (project-level)
 	globalSkills    string // global skills (~/.picoclaw/skills)
 	builtinSkills   string // builtin skills
+	whitelist        []string
+	whitelistEnabled bool
 }
 
 // SkillRoots returns all unique skill root directories used by this loader.
@@ -88,12 +90,14 @@ func (sl *SkillsLoader) SkillRoots() []string {
 	return out
 }
 
-func NewSkillsLoader(workspace string, globalSkills string, builtinSkills string) *SkillsLoader {
+func NewSkillsLoader(workspace string, globalSkills string, builtinSkills string, whitelist []string, whitelistEnabled bool) *SkillsLoader {
 	return &SkillsLoader{
 		workspace:       workspace,
 		workspaceSkills: filepath.Join(workspace, "skills"),
 		globalSkills:    globalSkills, // ~/.picoclaw/skills
 		builtinSkills:   builtinSkills,
+		whitelist:       whitelist,
+		whitelistEnabled: whitelistEnabled,
 	}
 }
 
@@ -101,6 +105,18 @@ func (sl *SkillsLoader) ListSkills() []SkillInfo {
 	skills := make([]SkillInfo, 0)
 	seen := make(map[string]bool)
 
+	isWhitelisted := func(name string) bool {
+		if !sl.whitelistEnabled {
+			return true
+		}
+		for _, w := range sl.whitelist {
+			if w == name {
+				return true
+			}
+		}
+		return false
+	}
+
 	addSkills := func(dir, source string) {
 		if dir == "" {
 			return
@@ -113,6 +129,12 @@ func (sl *SkillsLoader) ListSkills() []SkillInfo {
 			if !d.IsDir() {
 				continue
 			}
+
+			// First check if whitelisted before doing more expensive operations.
+			if !isWhitelisted(d.Name()) {
+				continue
+			}
+
 			skillFile := filepath.Join(dir, d.Name(), "SKILL.md")
 			if _, err := os.Stat(skillFile); err != nil {
 				continue
@@ -127,6 +149,12 @@ func (sl *SkillsLoader) ListSkills() []SkillInfo {
 				info.Description = metadata.Description
 				info.Name = metadata.Name
 			}
+
+			// Double check whitelisted name if metadata name is different from directory name
+			if info.Name != d.Name() && !isWhitelisted(info.Name) {
+				continue
+			}
+
 			if err := info.validate(); err != nil {
 				slog.Warn("invalid skill from "+source, "name", info.Name, "error", err)
 				continue
@@ -148,6 +176,19 @@ func (sl *SkillsLoader) ListSkills() []SkillInfo {
 }
 
 func (sl *SkillsLoader) LoadSkill(name string) (string, bool) {
+	if sl.whitelistEnabled {
+		whitelisted := false
+		for _, w := range sl.whitelist {
+			if w == name {
+				whitelisted = true
+				break
+			}
+		}
+		if !whitelisted {
+			return "", false
+		}
+	}
+
 	// 1. load from workspace skills first (project-level)
 	if sl.workspaceSkills != "" {
 		skillFile := filepath.Join(sl.workspaceSkills, name, "SKILL.md")
@@ -155,6 +196,7 @@ func (sl *SkillsLoader) LoadSkill(name string) (string, bool) {
 			return sl.stripFrontmatter(string(content)), true
 		}
 	}
+// ...
 
 	// 2. then load from global skills (~/.picoclaw/skills)
 	if sl.globalSkills != "" {
@@ -204,11 +246,11 @@ func (sl *SkillsLoader) BuildSkillsSummary() string {
 		escapedDesc := escapeXML(s.Description)
 		escapedPath := escapeXML(s.Path)
 
-		lines = append(lines, fmt.Sprintf("  <skill>"))
-		lines = append(lines, fmt.Sprintf("    <name>%s</name>", escapedName))
-		lines = append(lines, fmt.Sprintf("    <description>%s</description>", escapedDesc))
-		lines = append(lines, fmt.Sprintf("    <location>%s</location>", escapedPath))
-		lines = append(lines, fmt.Sprintf("    <source>%s</source>", s.Source))
+		lines = append(lines, "  <skill>")
+		lines = append(lines, "    <name>"+escapedName+"</name>")
+		lines = append(lines, "    <description>"+escapedDesc+"</description>")
+		lines = append(lines, "    <location>"+escapedPath+"</location>")
+		lines = append(lines, "    <source>"+s.Source+"</source>")
 		lines = append(lines, "  </skill>")
 	}
 	lines = append(lines, "</skills>")
diff --git a/pkg/skills/loader_test.go b/pkg/skills/loader_test.go
index 645d8b7ac..69d8b99db 100644
--- a/pkg/skills/loader_test.go
+++ b/pkg/skills/loader_test.go
@@ -155,7 +155,7 @@ func TestListSkillsWorkspaceOverridesGlobal(t *testing.T) {
 	createSkillDir(t, filepath.Join(ws, "skills"), "my-skill", "my-skill", "workspace version")
 	createSkillDir(t, global, "my-skill", "my-skill", "global version")
 
-	sl := NewSkillsLoader(ws, global, "")
+	sl := NewSkillsLoader(ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -172,7 +172,7 @@ func TestListSkillsGlobalOverridesBuiltin(t *testing.T) {
 	createSkillDir(t, global, "my-skill", "my-skill", "global version")
 	createSkillDir(t, builtin, "my-skill", "my-skill", "builtin version")
 
-	sl := NewSkillsLoader(ws, global, builtin)
+	sl := NewSkillsLoader(ws, global, builtin, nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -189,7 +189,7 @@ func TestListSkillsMetadataNameDedup(t *testing.T) {
 	createSkillDir(t, filepath.Join(ws, "skills"), "dir-a", "shared-name", "workspace version")
 	createSkillDir(t, global, "dir-b", "shared-name", "global version")
 
-	sl := NewSkillsLoader(ws, global, "")
+	sl := NewSkillsLoader(ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -207,7 +207,7 @@ func TestListSkillsMultipleDistinctSkills(t *testing.T) {
 	createSkillDir(t, global, "skill-b", "skill-b", "desc b")
 	createSkillDir(t, builtin, "skill-c", "skill-c", "desc c")
 
-	sl := NewSkillsLoader(ws, global, builtin)
+	sl := NewSkillsLoader(ws, global, builtin, nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 3)
@@ -230,7 +230,7 @@ func TestListSkillsInvalidSkillSkipped(t *testing.T) {
 	// Valid skill
 	createSkillDir(t, global, "good-skill", "good-skill", "desc")
 
-	sl := NewSkillsLoader(ws, global, "")
+	sl := NewSkillsLoader(ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -243,7 +243,7 @@ func TestListSkillsEmptyAndNonexistentDirs(t *testing.T) {
 	emptyDir := filepath.Join(tmp, "empty")
 	require.NoError(t, os.MkdirAll(emptyDir, 0o755))
 
-	sl := NewSkillsLoader(ws, emptyDir, filepath.Join(tmp, "nonexistent"))
+	sl := NewSkillsLoader(ws, emptyDir, filepath.Join(tmp, "nonexistent"), nil, false)
 	skills := sl.ListSkills()
 
 	assert.Empty(t, skills)
@@ -259,7 +259,7 @@ func TestListSkillsDirWithoutSkillMD(t *testing.T) {
 	// Valid skill alongside
 	createSkillDir(t, global, "real-skill", "real-skill", "desc")
 
-	sl := NewSkillsLoader(ws, global, "")
+	sl := NewSkillsLoader(ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -333,7 +333,7 @@ func TestSkillRootsTrimsWhitespaceAndDedups(t *testing.T) {
 	global := filepath.Join(tmp, "global")
 	builtin := filepath.Join(tmp, "builtin")
 
-	sl := NewSkillsLoader(workspace, "  "+global+"  ", "\t"+builtin+"\n")
+	sl := NewSkillsLoader(workspace, "  "+global+"  ", "\t"+builtin+"\n", nil, false)
 	roots := sl.SkillRoots()
 
 	assert.Equal(t, []string{
@@ -417,3 +417,47 @@ func TestGetSkillMetadata_IgnoresHTMLCommentBlocks(t *testing.T) {
 	assert.Equal(t, "biomed-skill", meta.Name)
 	assert.Equal(t, "Summarize biomedical papers.", meta.Description)
 }
+func TestListSkillsWithWhitelist(t *testing.T) {
+	tmp := t.TempDir()
+	ws := filepath.Join(tmp, "workspace")
+	global := filepath.Join(tmp, "global")
+	builtin := filepath.Join(tmp, "builtin")
+
+	createSkillDir(t, filepath.Join(ws, "skills"), "skill-a", "skill-a", "desc a")
+	createSkillDir(t, global, "skill-b", "skill-b", "desc b")
+	createSkillDir(t, builtin, "skill-c", "skill-c", "desc c")
+
+	t.Run("allow-one", func(t *testing.T) {
+		sl := NewSkillsLoader(ws, global, builtin, []string{"skill-a"}, true)
+		skills := sl.ListSkills()
+		assert.Len(t, skills, 1)
+		assert.Equal(t, "skill-a", skills[0].Name)
+	})
+
+	t.Run("allow-two", func(t *testing.T) {
+		sl := NewSkillsLoader(ws, global, builtin, []string{"skill-a", "skill-c"}, true)
+		skills := sl.ListSkills()
+		assert.Len(t, skills, 2)
+		names := []string{skills[0].Name, skills[1].Name}
+		assert.Contains(t, names, "skill-a")
+		assert.Contains(t, names, "skill-c")
+	})
+
+	t.Run("allow-none", func(t *testing.T) {
+		sl := NewSkillsLoader(ws, global, builtin, []string{"non-existent"}, true)
+		skills := sl.ListSkills()
+		assert.Empty(t, skills)
+	})
+
+	t.Run("empty-whitelist-allows-all", func(t *testing.T) {
+		sl := NewSkillsLoader(ws, global, builtin, []string{}, false)
+		skills := sl.ListSkills()
+		assert.Len(t, skills, 3)
+	})
+
+	t.Run("nil-whitelist-allows-all", func(t *testing.T) {
+		sl := NewSkillsLoader(ws, global, builtin, nil, false)
+		skills := sl.ListSkills()
+		assert.Len(t, skills, 3)
+	})
+}
diff --git a/pkg/tools/registry.go b/pkg/tools/registry.go
index e51dff71a..bb179509d 100644
--- a/pkg/tools/registry.go
+++ b/pkg/tools/registry.go
@@ -423,21 +423,32 @@ func (r *ToolRegistry) GetSummaries() []string {
 	return summaries
 }
 
-// GetAll returns all registered tools (both core and non-core with TTL > 0).
-// Used by SubTurn to inherit parent's tool set.
-func (r *ToolRegistry) GetAll() []Tool {
-	r.mu.RLock()
-	defer r.mu.RUnlock()
+// Filter removes tools that are not in the whitelist.
+// If enabled is false, it does nothing.
+func (r *ToolRegistry) Filter(whitelist []string, enabled bool) {
+	if !enabled {
+		return
+	}
 
-	sorted := r.sortedToolNames()
-	tools := make([]Tool, 0, len(sorted))
-	for _, name := range sorted {
-		entry := r.tools[name]
+	r.mu.Lock()
+	defer r.mu.Unlock()
 
-		// Include core tools and non-core tools with active TTL
-		if entry.IsCore || entry.TTL > 0 {
-			tools = append(tools, entry.Tool)
+	whitelistMap := make(map[string]struct{}, len(whitelist))
+	for _, name := range whitelist {
+		whitelistMap[name] = struct{}{}
+	}
+
+	removed := 0
+	for name := range r.tools {
+		if _, allowed := whitelistMap[name]; !allowed {
+			delete(r.tools, name)
+			removed++
 		}
 	}
-	return tools
+
+	if removed > 0 {
+		r.version.Add(1)
+		logger.InfoCF("tools", "Filtered tools based on whitelist",
+			map[string]any{"removed": removed, "remaining": len(r.tools)})
+	}
 }
diff --git a/pkg/tools/skills_install.go b/pkg/tools/skills_install.go
index 71bfe730b..77eb44655 100644
--- a/pkg/tools/skills_install.go
+++ b/pkg/tools/skills_install.go
@@ -15,22 +15,23 @@ import (
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
-// InstallSkillTool allows the LLM agent to install skills from registries.
-// It shares the same RegistryManager that FindSkillsTool uses,
-// so all registries configured in config are available for installation.
 type InstallSkillTool struct {
-	registryMgr *skills.RegistryManager
-	workspace   string
-	mu          sync.Mutex
+	registryMgr      *skills.RegistryManager
+	workspace        string
+	whitelist        []string
+	whitelistEnabled bool
+	mu               sync.Mutex
 }
 
 // NewInstallSkillTool creates a new InstallSkillTool.
 // registryMgr is the shared registry manager (same instance as FindSkillsTool).
 // workspace is the root workspace directory; skills install to {workspace}/skills/{slug}/.
-func NewInstallSkillTool(registryMgr *skills.RegistryManager, workspace string) *InstallSkillTool {
+func NewInstallSkillTool(registryMgr *skills.RegistryManager, workspace string, whitelist []string, whitelistEnabled bool) *InstallSkillTool {
 	return &InstallSkillTool{
 		registryMgr: registryMgr,
 		workspace:   workspace,
+		whitelist:   whitelist,
+		whitelistEnabled: whitelistEnabled,
 		mu:          sync.Mutex{},
 	}
 }
@@ -80,6 +81,20 @@ func (t *InstallSkillTool) Execute(ctx context.Context, args map[string]any) *To
 		return ErrorResult(fmt.Sprintf("invalid slug %q: error: %s", slug, err.Error()))
 	}
 
+	// Check whitelist
+	if t.whitelistEnabled {
+		whitelisted := false
+		for _, w := range t.whitelist {
+			if w == slug {
+				whitelisted = true
+				break
+			}
+		}
+		if !whitelisted {
+			return ErrorResult(fmt.Sprintf("skill %q is not in whitelist and cannot be installed", slug))
+		}
+	}
+
 	// Validate registry
 	registryName, _ := args["registry"].(string)
 	if err := utils.ValidateSkillIdentifier(registryName); err != nil {
diff --git a/pkg/tools/skills_install_test.go b/pkg/tools/skills_install_test.go
index 676fcecc0..4d90b7fcc 100644
--- a/pkg/tools/skills_install_test.go
+++ b/pkg/tools/skills_install_test.go
@@ -13,19 +13,19 @@ import (
 )
 
 func TestInstallSkillToolName(t *testing.T) {
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir(), nil, false)
 	assert.Equal(t, "install_skill", tool.Name())
 }
 
 func TestInstallSkillToolMissingSlug(t *testing.T) {
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir(), nil, false)
 	result := tool.Execute(context.Background(), map[string]any{})
 	assert.True(t, result.IsError)
 	assert.Contains(t, result.ForLLM, "identifier is required and must be a non-empty string")
 }
 
 func TestInstallSkillToolEmptySlug(t *testing.T) {
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir(), nil, false)
 	result := tool.Execute(context.Background(), map[string]any{
 		"slug": "   ",
 	})
@@ -34,7 +34,7 @@ func TestInstallSkillToolEmptySlug(t *testing.T) {
 }
 
 func TestInstallSkillToolUnsafeSlug(t *testing.T) {
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir(), nil, false)
 
 	cases := []string{
 		"../etc/passwd",
@@ -56,7 +56,7 @@ func TestInstallSkillToolAlreadyExists(t *testing.T) {
 	skillDir := filepath.Join(workspace, "skills", "existing-skill")
 	require.NoError(t, os.MkdirAll(skillDir, 0o755))
 
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), workspace)
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), workspace, nil, false)
 	result := tool.Execute(context.Background(), map[string]any{
 		"slug":     "existing-skill",
 		"registry": "clawhub",
@@ -67,7 +67,7 @@ func TestInstallSkillToolAlreadyExists(t *testing.T) {
 
 func TestInstallSkillToolRegistryNotFound(t *testing.T) {
 	workspace := t.TempDir()
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), workspace)
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), workspace, nil, false)
 	result := tool.Execute(context.Background(), map[string]any{
 		"slug":     "some-skill",
 		"registry": "nonexistent",
@@ -78,7 +78,7 @@ func TestInstallSkillToolRegistryNotFound(t *testing.T) {
 }
 
 func TestInstallSkillToolParameters(t *testing.T) {
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir(), nil, false)
 	params := tool.Parameters()
 
 	props, ok := params["properties"].(map[string]any)
@@ -95,10 +95,55 @@ func TestInstallSkillToolParameters(t *testing.T) {
 }
 
 func TestInstallSkillToolMissingRegistry(t *testing.T) {
-	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir(), nil, false)
 	result := tool.Execute(context.Background(), map[string]any{
 		"slug": "some-skill",
 	})
 	assert.True(t, result.IsError)
 	assert.Contains(t, result.ForLLM, "invalid registry")
 }
+func TestInstallSkillToolWhitelist(t *testing.T) {
+	workspace := t.TempDir()
+	rm := skills.NewRegistryManager()
+
+	t.Run("blocked-by-whitelist", func(t *testing.T) {
+		tool := NewInstallSkillTool(rm, workspace, []string{"allowed-skill"}, true)
+		result := tool.Execute(context.Background(), map[string]any{
+			"slug":     "blocked-skill",
+			"registry": "clawhub",
+		})
+		assert.True(t, result.IsError)
+		assert.Contains(t, result.ForLLM, "not in whitelist")
+	})
+
+	t.Run("allowed-by-whitelist", func(t *testing.T) {
+		// This will still fail because registry is not found, but it should pass the whitelist check
+		tool := NewInstallSkillTool(rm, workspace, []string{"allowed-skill"}, true)
+		result := tool.Execute(context.Background(), map[string]any{
+			"slug":     "allowed-skill",
+			"registry": "clawhub",
+		})
+		assert.True(t, result.IsError)
+		assert.NotContains(t, result.ForLLM, "not in whitelist")
+	})
+
+	t.Run("empty-whitelist-allows-all", func(t *testing.T) {
+		tool := NewInstallSkillTool(rm, workspace, []string{}, false)
+		result := tool.Execute(context.Background(), map[string]any{
+			"slug":     "any-skill",
+			"registry": "clawhub",
+		})
+		assert.True(t, result.IsError)
+		assert.NotContains(t, result.ForLLM, "not in whitelist")
+	})
+
+	t.Run("nil-whitelist-allows-all", func(t *testing.T) {
+		tool := NewInstallSkillTool(rm, workspace, nil, false)
+		result := tool.Execute(context.Background(), map[string]any{
+			"slug":     "any-skill",
+			"registry": "clawhub",
+		})
+		assert.True(t, result.IsError)
+		assert.NotContains(t, result.ForLLM, "not in whitelist")
+	})
+}
diff --git a/pkg/tools/skills_search.go b/pkg/tools/skills_search.go
index 2b6cffd38..bf5c8e8e9 100644
--- a/pkg/tools/skills_search.go
+++ b/pkg/tools/skills_search.go
@@ -12,15 +12,19 @@ import (
 type FindSkillsTool struct {
 	registryMgr *skills.RegistryManager
 	cache       *skills.SearchCache
+	whitelist   []string
+	enabled     bool
 }
 
 // NewFindSkillsTool creates a new FindSkillsTool.
 // registryMgr is the shared registry manager (built from config in createToolRegistry).
 // cache is the search cache for deduplicating similar queries.
-func NewFindSkillsTool(registryMgr *skills.RegistryManager, cache *skills.SearchCache) *FindSkillsTool {
+func NewFindSkillsTool(registryMgr *skills.RegistryManager, cache *skills.SearchCache, whitelist []string, enabled bool) *FindSkillsTool {
 	return &FindSkillsTool{
 		registryMgr: registryMgr,
 		cache:       cache,
+		whitelist:   whitelist,
+		enabled:     enabled,
 	}
 }
 
@@ -79,6 +83,22 @@ func (t *FindSkillsTool) Execute(ctx context.Context, args map[string]any) *Tool
 		return ErrorResult(fmt.Sprintf("skill search failed: %v", err))
 	}
 
+	// Filter by whitelist if enabled
+	if t.enabled {
+		filtered := make([]skills.SearchResult, 0, len(results))
+		whitelistMap := make(map[string]struct{}, len(t.whitelist))
+		for _, w := range t.whitelist {
+			whitelistMap[w] = struct{}{}
+		}
+		for _, r := range results {
+			if _, ok := whitelistMap[r.Slug]; ok {
+				filtered = append(filtered, r)
+			}
+		}
+		results = filtered
+	}
+
+
 	// Cache the results.
 	if t.cache != nil && len(results) > 0 {
 		t.cache.Put(query, results)
diff --git a/pkg/tools/skills_search_test.go b/pkg/tools/skills_search_test.go
index 0e5387cf5..7d2955b3b 100644
--- a/pkg/tools/skills_search_test.go
+++ b/pkg/tools/skills_search_test.go
@@ -10,19 +10,19 @@ import (
 )
 
 func TestFindSkillsToolName(t *testing.T) {
-	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil, nil, false)
 	assert.Equal(t, "find_skills", tool.Name())
 }
 
 func TestFindSkillsToolMissingQuery(t *testing.T) {
-	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil, nil, false)
 	result := tool.Execute(context.Background(), map[string]any{})
 	assert.True(t, result.IsError)
 	assert.Contains(t, result.ForLLM, "query is required")
 }
 
 func TestFindSkillsToolEmptyQuery(t *testing.T) {
-	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil, nil, false)
 	result := tool.Execute(context.Background(), map[string]any{
 		"query": "   ",
 	})
@@ -35,7 +35,7 @@ func TestFindSkillsToolCacheHit(t *testing.T) {
 		{Slug: "github", Score: 0.9, RegistryName: "clawhub"},
 	})
 
-	tool := NewFindSkillsTool(skills.NewRegistryManager(), cache)
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), cache, nil, false)
 	result := tool.Execute(context.Background(), map[string]any{
 		"query": "github",
 	})
@@ -46,7 +46,7 @@ func TestFindSkillsToolCacheHit(t *testing.T) {
 }
 
 func TestFindSkillsToolParameters(t *testing.T) {
-	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil, nil, false)
 	params := tool.Parameters()
 
 	props, ok := params["properties"].(map[string]any)
@@ -60,7 +60,7 @@ func TestFindSkillsToolParameters(t *testing.T) {
 }
 
 func TestFindSkillsToolDescription(t *testing.T) {
-	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil, nil, false)
 	assert.NotEmpty(t, tool.Description())
 	assert.Contains(t, tool.Description(), "skill")
 }
diff --git a/workspace/HEARTBEAT.md b/workspace/HEARTBEAT.md
new file mode 100644
index 000000000..9a4e3ca80
--- /dev/null
+++ b/workspace/HEARTBEAT.md
@@ -0,0 +1,22 @@
+# Heartbeat Check List
+
+This file contains tasks for the heartbeat service to check periodically.
+
+## Examples
+
+- Check for unread messages
+- Review upcoming calendar events
+- Check device status (e.g., MaixCam)
+
+## Instructions
+
+- Execute ALL tasks listed below. Do NOT skip any task.
+- For simple tasks (e.g., report current time), respond directly.
+- For complex tasks that may take time, use the spawn tool to create a subagent.
+- The spawn tool is async - subagent results will be sent to the user automatically.
+- After spawning a subagent, CONTINUE to process remaining tasks.
+- Only respond with HEARTBEAT_OK when ALL tasks are done AND nothing needs attention.
+
+---
+
+Add your heartbeat tasks below this line:
diff --git a/workspace/cron/jobs.json b/workspace/cron/jobs.json
new file mode 100644
index 000000000..b8cdc503b
--- /dev/null
+++ b/workspace/cron/jobs.json
@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "jobs": []
+}
\ No newline at end of file
diff --git a/workspace/heartbeat.log b/workspace/heartbeat.log
new file mode 100644
index 000000000..8fb65ced5
--- /dev/null
+++ b/workspace/heartbeat.log
@@ -0,0 +1 @@
+[2026-03-24 08:15:50] [INFO] Created default HEARTBEAT.md template
diff --git a/workspace/state/state.json b/workspace/state/state.json
new file mode 100644
index 000000000..912b9bc59
--- /dev/null
+++ b/workspace/state/state.json
@@ -0,0 +1,4 @@
+{
+  "last_channel": "telegram:8271300679",
+  "timestamp": "2026-03-24T08:43:14.295101255+01:00"
+}
\ No newline at end of file

From 968e77225abdb9fb42dc018f29e9b25a7a32cbb7 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Wed, 25 Mar 2026 08:53:44 +0100
Subject: [PATCH 03/25] chore: ignore workspace/ runtime state

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index b869ecc33..449d06f8a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,3 +67,4 @@ web/backend/dist/*
 .claude/
 
 docker/data
+workspace/

From 3c6639517dbf779f4c60e9ff915ab532041db04f Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Tue, 24 Mar 2026 11:27:04 +0100
Subject: [PATCH 04/25] azure skills whitelisting: fix skills loader, security
 config, and tests

---
 Makefile                                |   2 +-
 cmd/picoclaw/internal/skills/command.go |   2 +-
 pkg/agent/context.go                    |   2 +-
 pkg/agent/loop.go                       |  18 +-
 pkg/config/config.go                    |   2 +-
 pkg/config/security_integration_test.go |   3 +-
 pkg/gateway/gateway.go                  |   1 -
 pkg/health/server.go                    | 248 +++++++++++-------------
 pkg/providers/factory_provider.go       |  30 +++
 pkg/providers/http_provider.go          |   1 -
 pkg/providers/openai_compat/provider.go |  35 +++-
 pkg/skills/loader.go                    |  28 +--
 pkg/skills/loader_test.go               |   1 +
 pkg/tools/skills_install.go             |  15 +-
 pkg/tools/skills_install_test.go        |   1 +
 pkg/tools/skills_search.go              |   8 +-
 web/Makefile                            |   8 +-
 web/backend/api/models.go               |  22 ++-
 web/backend/api/skills.go               |   2 +
 19 files changed, 252 insertions(+), 177 deletions(-)

diff --git a/Makefile b/Makefile
index 4704b7c4a..42e6c299b 100644
--- a/Makefile
+++ b/Makefile
@@ -273,7 +273,7 @@ test: generate
 
 ## fmt: Format Go code
 fmt:
-	@$(GOLANGCI_LINT) fmt
+	@gofmt -s -w $$(find . -name "*.go" -not -path "./web/*" -not -path "./vendor/*")
 
 ## lint: Run linters
 lint:
diff --git a/cmd/picoclaw/internal/skills/command.go b/cmd/picoclaw/internal/skills/command.go
index e8b884977..4df257140 100644
--- a/cmd/picoclaw/internal/skills/command.go
+++ b/cmd/picoclaw/internal/skills/command.go
@@ -43,7 +43,7 @@ func NewSkillsCommand() *cobra.Command {
 			globalDir := filepath.Dir(internal.GetConfigPath())
 			globalSkillsDir := filepath.Join(globalDir, "skills")
 			builtinSkillsDir := filepath.Join(globalDir, "picoclaw", "skills")
-			d.skillsLoader = skills.NewSkillsLoader(d.workspace, globalSkillsDir, builtinSkillsDir)
+			d.skillsLoader = skills.NewSkillsLoader(d.workspace, globalSkillsDir, builtinSkillsDir, nil, false)
 
 			return nil
 		},
diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index c2921294b..2666faf91 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -73,7 +73,7 @@ func NewContextBuilder(workspace string) *ContextBuilder {
 
 	return &ContextBuilder{
 		workspace:    workspace,
-		skillsLoader: skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir),
+		skillsLoader: skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir, nil, false),
 		memory:       NewMemoryStore(workspace),
 	}
 }
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index a54dbffbe..6cfbe1a56 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -327,11 +327,25 @@ func registerSharedTools(
 					cfg.Tools.Skills.SearchCache.MaxSize,
 					time.Duration(cfg.Tools.Skills.SearchCache.TTLSeconds)*time.Second,
 				)
-				agent.Tools.Register(tools.NewFindSkillsTool(registryMgr, searchCache, cfg.Tools.Skills.Whitelist, cfg.Tools.Skills.WhitelistEnabled))
+				agent.Tools.Register(
+					tools.NewFindSkillsTool(
+						registryMgr,
+						searchCache,
+						cfg.Tools.Skills.Whitelist,
+						cfg.Tools.Skills.WhitelistEnabled,
+					),
+				)
 			}
 
 			if install_skills_enable {
-				agent.Tools.Register(tools.NewInstallSkillTool(registryMgr, agent.Workspace, cfg.Tools.Skills.Whitelist, cfg.Tools.Skills.WhitelistEnabled))
+				agent.Tools.Register(
+					tools.NewInstallSkillTool(
+						registryMgr,
+						agent.Workspace,
+						cfg.Tools.Skills.Whitelist,
+						cfg.Tools.Skills.WhitelistEnabled,
+					),
+				)
 			}
 		}
 
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 5b88a0146..2839b605a 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -893,7 +893,7 @@ type ToolsConfig struct {
 	MediaCleanup    MediaCleanupConfig `json:"media_cleanup"     yaml:"-"`
 	Whitelist        FlexibleStringSlice `json:"whitelist,omitempty"         yaml:"-" env:"PICOCLAW_TOOLS_WHITELIST"`
 	WhitelistEnabled bool                `json:"whitelist_enabled,omitempty" yaml:"-" env:"PICOCLAW_TOOLS_WHITELIST_ENABLED"`
-	MCP             MCPConfig          `json:"mcp"               yaml:"-""`
+	MCP             MCPConfig          `json:"mcp"               yaml:"-"`
 	AppendFile      ToolConfig         `json:"append_file"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_APPEND_FILE_"`
 	EditFile        ToolConfig         `json:"edit_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_EDIT_FILE_"`
 	FindSkills      ToolConfig         `json:"find_skills"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_FIND_SKILLS_"`
diff --git a/pkg/config/security_integration_test.go b/pkg/config/security_integration_test.go
index 6ca8637f4..75a8c2daf 100644
--- a/pkg/config/security_integration_test.go
+++ b/pkg/config/security_integration_test.go
@@ -34,8 +34,9 @@ func TestJSONUnmarshalPrivateFields(t *testing.T) {
 	if s.PublicField != "pub" {
 		t.Errorf("PublicField = %q, want 'pub'", s.PublicField)
 	}
+	// Private fields cannot be unmarshaled from JSON
 	if s.privateField != "" {
-		t.Errorf("privateField = %q, want empty because unexported fields are ignored", s.privateField)
+		t.Errorf("privateField = %q, want empty string (private fields are not unmarshaled)", s.privateField)
 	}
 }
 
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
index 6f6911122..bf1d90e70 100644
--- a/pkg/gateway/gateway.go
+++ b/pkg/gateway/gateway.go
@@ -216,7 +216,6 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 		})
 	}
 
-
 	fmt.Printf("✓ Gateway started on %s:%d\n", cfg.Gateway.Host, cfg.Gateway.Port)
 	fmt.Println("Press Ctrl+C to stop")
 
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 16447a3c6..62c1b606b 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -2,15 +2,28 @@ package health
 
 import (
 	"context"
-	"crypto/subtle"
 	"encoding/json"
 	"fmt"
 	"maps"
 	"net/http"
+	"os"
 	"sync"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
+// ChatRequest is the JSON body for POST /chat.
+type ChatRequest struct {
+	Message   string `json:"message"`
+	SessionID string `json:"session_id,omitempty"`
+}
+
+// ChatResponse is the JSON response from POST /chat.
+type ChatResponse struct {
+	Response string `json:"response"`
+}
+
 type Server struct {
 	server     *http.Server
 	mu         sync.RWMutex
@@ -23,7 +36,6 @@ type Server struct {
 	apiKey     string
 }
 
-
 type Check struct {
 	Name      string    `json:"name"`
 	Status    string    `json:"status"`
@@ -35,6 +47,7 @@ type StatusResponse struct {
 	Status string           `json:"status"`
 	Uptime string           `json:"uptime"`
 	Checks map[string]Check `json:"checks,omitempty"`
+	Pid    int              `json:"pid"`
 }
 
 func NewServer(host string, port int, token string) *Server {
@@ -51,13 +64,13 @@ func NewServer(host string, port int, token string) *Server {
 	mux.HandleFunc("/reload", s.reloadHandler)
 	mux.HandleFunc("/chat", s.chatHandler)
 
-
 	addr := fmt.Sprintf("%s:%d", host, port)
 	s.server = &http.Server{
-		Addr:         addr,
-		Handler:      mux,
-		ReadTimeout:  5 * time.Second,
-		WriteTimeout: 5 * time.Second,
+		Addr:        addr,
+		Handler:     mux,
+		ReadTimeout: 10 * time.Second,
+		// WriteTimeout must be long enough for LLM inference; 5 min is generous.
+		WriteTimeout: 5 * time.Minute,
 	}
 
 	return s
@@ -121,7 +134,39 @@ func (s *Server) SetReloadFunc(fn func() error) {
 	s.reloadFunc = fn
 }
 
+// SetChatFunc sets the callback that processes /chat requests.
+// fn receives the user message and an optional session ID and must return the
+// agent's reply (or an error). It is called synchronously inside the HTTP
+// handler, so the write timeout on the server governs the maximum duration.
+func (s *Server) SetChatFunc(fn func(ctx context.Context, message, sessionID string) (string, error)) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.chatFunc = fn
+}
+
+// SetAPIKey sets the expected X-API-Key header value.
+func (s *Server) SetAPIKey(key string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.apiKey = key
+}
+
+func (s *Server) verifyAPIKey(r *http.Request) bool {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	if s.apiKey == "" {
+		return true
+	}
+	return r.Header.Get("X-API-Key") == s.apiKey
+}
+
 func (s *Server) reloadHandler(w http.ResponseWriter, r *http.Request) {
+	if !s.verifyAPIKey(r) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusUnauthorized)
+		json.NewEncoder(w).Encode(map[string]string{"error": "unauthorized"})
+		return
+	}
 	if r.Method != http.MethodPost {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusMethodNotAllowed)
@@ -129,21 +174,6 @@ func (s *Server) reloadHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Token check
-	s.mu.RLock()
-	requiredToken := s.authToken
-	s.mu.RUnlock()
-
-	if requiredToken != "" {
-		given := extractBearerToken(r.Header.Get("Authorization"))
-		if given == "" || subtle.ConstantTimeCompare([]byte(given), []byte(requiredToken)) != 1 {
-			w.Header().Set("Content-Type", "application/json")
-			w.WriteHeader(http.StatusUnauthorized)
-			json.NewEncoder(w).Encode(map[string]string{"error": "unauthorized"})
-			return
-		}
-	}
-
 	s.mu.Lock()
 	reloadFunc := s.reloadFunc
 	s.mu.Unlock()
@@ -175,6 +205,7 @@ func (s *Server) healthHandler(w http.ResponseWriter, r *http.Request) {
 	resp := StatusResponse{
 		Status: "ok",
 		Uptime: uptime.String(),
+		Pid:    os.Getpid(),
 	}
 
 	json.NewEncoder(w).Encode(resp)
@@ -218,20 +249,72 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
-// HandlerMux is the interface for registering HTTP handlers, used by
-// RegisterOnMux so that callers can pass any mux implementation
-// (e.g. *http.ServeMux or a custom dynamic mux).
-type HandlerMux interface {
-	Handle(pattern string, handler http.Handler)
-	HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
-}
-
-// RegisterOnMux registers /health, /ready and /reload handlers onto the given mux.
-// This allows the health endpoints to be served by a shared HTTP server.
-func (s *Server) RegisterOnMux(mux HandlerMux) {
+// RegisterOnMux registers /health, /ready, /reload and /chat handlers onto the
+// given mux. This allows the health endpoints to be served by a shared HTTP server.
+func (s *Server) RegisterOnMux(mux *http.ServeMux) {
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
 	mux.HandleFunc("/reload", s.reloadHandler)
+	mux.HandleFunc("/chat", s.chatHandler)
+	mux.HandleFunc("/v1/chat/completions", func(w http.ResponseWriter, r *http.Request) {
+		logger.Error("GATEWAY IS HITTING ITSELF FOR LLM CALLS!")
+		http.Error(w, "GATEWAY LOOP DETECTION", http.StatusLoopDetected)
+	})
+}
+
+// chatHandler handles POST /chat — a synchronous HTTP chat API.
+// Request body:  {"message": "...", "session_id": "..." (optional)}
+// Response body: {"response": "..."}
+func (s *Server) chatHandler(w http.ResponseWriter, r *http.Request) {
+	if !s.verifyAPIKey(r) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusUnauthorized)
+		json.NewEncoder(w).Encode(map[string]string{"error": "unauthorized"})
+		return
+	}
+	if r.Method != http.MethodPost {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusMethodNotAllowed)
+		json.NewEncoder(w).Encode(map[string]string{"error": "method not allowed, use POST"})
+		return
+	}
+
+	s.mu.RLock()
+	chatFunc := s.chatFunc
+	s.mu.RUnlock()
+
+	if chatFunc == nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusServiceUnavailable)
+		json.NewEncoder(w).Encode(map[string]string{"error": "chat not configured"})
+		return
+	}
+
+	var req ChatRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]string{"error": "invalid JSON: " + err.Error()})
+		return
+	}
+	if req.Message == "" {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]string{"error": "message field is required"})
+		return
+	}
+
+	reply, err := chatFunc(r.Context(), req.Message, req.SessionID)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(ChatResponse{Response: reply})
 }
 
 func statusString(ok bool) string {
@@ -240,102 +323,3 @@ func statusString(ok bool) string {
 	}
 	return "fail"
 }
-
-// extractBearerToken returns the token from an "Authorization: Bearer <t>" header,
-// or the empty string if the header is missing or malformed.
-func extractBearerToken(header string) string {
-	const prefix = "Bearer "
-	if len(header) < len(prefix) {
-		return ""
-	}
-	if header[:len(prefix)] != prefix {
-		return ""
-	}
-	return header[len(prefix):]
-}
-
-// SetChatFunc sets the callback that processes /chat requests.
-func (s *Server) SetChatFunc(fn func(ctx context.Context, message, sessionID string) (string, error)) {
-s.mu.Lock()
-defer s.mu.Unlock()
-s.chatFunc = fn
-}
-
-// SetAPIKey sets the expected X-API-Key header value.
-func (s *Server) SetAPIKey(key string) {
-s.mu.Lock()
-defer s.mu.Unlock()
-s.apiKey = key
-}
-
-func (s *Server) verifyAPIKey(r *http.Request) bool {
-s.mu.RLock()
-defer s.mu.RUnlock()
-if s.apiKey == "" {
- true
-}
-return r.Header.Get("X-API-Key") == s.apiKey
-}
-
-// ChatRequest is the JSON body for POST /chat.
-type ChatRequest struct {
-Message   string `json:"message"`
-SessionID string `json:"session_id,omitempty"`
-}
-
-// ChatResponse is the JSON response from POST /chat.
-type ChatResponse struct {
-Response string `json:"response"`
-}
-
-func (s *Server) chatHandler(w http.ResponseWriter, r *http.Request) {
-if !s.verifyAPIKey(r) {
-tent-Type", "application/json")
-authorized)
-.NewEncoder(w).Encode(map[string]string{"error": "unauthorized"})
-
-}
-if r.Method != http.MethodPost {
-tent-Type", "application/json")
-otAllowed)
-.NewEncoder(w).Encode(map[string]string{"error": "method not allowed, use POST"})
-
-}
-
-s.mu.RLock()
-chatFunc := s.chatFunc
-s.mu.RUnlock()
-
-if chatFunc == nil {
-tent-Type", "application/json")
-available)
-.NewEncoder(w).Encode(map[string]string{"error": "chat not configured"})
-
-}
-
-var req ChatRequest
-if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-tent-Type", "application/json")
-uest)
-.NewEncoder(w).Encode(map[string]string{"error": "invalid JSON: " + err.Error()})
-
-}
-if req.Message == "" {
-tent-Type", "application/json")
-uest)
-.NewEncoder(w).Encode(map[string]string{"error": "message field is required"})
-
-}
-
-reply, err := chatFunc(r.Context(), req.Message, req.SessionID)
-if err != nil {
-tent-Type", "application/json")
-ternalServerError)
-.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
-
-}
-
-w.Header().Set("Content-Type", "application/json")
-w.WriteHeader(http.StatusOK)
-json.NewEncoder(w).Encode(ChatResponse{Response: reply})
-}
diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index ab7277fae..653d8732f 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -240,6 +240,36 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 			cfg.ExtraBody,
 		), modelID, nil
 
+	case "nvidia":
+		apiBase := cfg.APIBase
+		if apiBase == "" {
+			apiBase = getDefaultAPIBase(protocol)
+		}
+		p := NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+			cfg.APIKey(),
+			apiBase,
+			cfg.Proxy,
+			cfg.MaxTokensField,
+			cfg.RequestTimeout,
+			cfg.ExtraBody,
+		)
+		// NVIDIA sometimes prefers api-key header or has issues with Bearer in some environments
+		p.SetUseAzureHeaders(false) // NVIDIA main gateway prefers standard Bearer headers; api-key causes 404s
+		return p, "nvidia/" + modelID, nil
+
+	case "azure-ai", "azure-foundry":
+		// Azure AI Foundry / Studio compatible with OpenAI API format,
+		// but using api-key header instead of Authorization: Bearer.
+		if cfg.APIKey() == "" && cfg.APIBase == "" {
+			return nil, "", fmt.Errorf("api_key or api_base is required for protocol %q", protocol)
+		}
+		return NewAzureAIProvider(
+			cfg.APIKey(),
+			cfg.APIBase,
+			cfg.Proxy,
+			cfg.RequestTimeout,
+		), modelID, nil
+
 	case "minimax":
 		// Minimax requires reasoning_split: true in the request body
 		if cfg.APIKey() == "" && cfg.APIBase == "" {
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index b5cf0b8cd..6df03c606 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -91,4 +91,3 @@ func (p *HTTPProvider) SetUseAzureHeaders(use bool) {
 func (p *HTTPProvider) SupportsNativeSearch() bool {
 	return p.delegate.SupportsNativeSearch()
 }
-
diff --git a/pkg/providers/openai_compat/provider.go b/pkg/providers/openai_compat/provider.go
index d4c3da2d9..279b518f5 100644
--- a/pkg/providers/openai_compat/provider.go
+++ b/pkg/providers/openai_compat/provider.go
@@ -11,8 +11,10 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+	"sync"
 	"time"
 
+
 	"github.com/sipeed/picoclaw/pkg/providers/common"
 	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
 )
@@ -31,14 +33,18 @@ type (
 )
 
 type Provider struct {
-	apiKey         string
-	apiBase        string
-	maxTokensField string // Field name for max tokens (e.g., "max_completion_tokens" for o1/glm models)
-	httpClient     *http.Client
-	extraBody      map[string]any // Additional fields to inject into request body
-	userAgent      string
+	apiKey          string
+	apiBase         string
+	maxTokensField  string // Field name for max tokens (e.g., "max_completion_tokens" for o1/glm models)
+	httpClient      *http.Client
+	extraBody       map[string]any // Additional fields to inject into request body
+	userAgent       string
+	useAzureHeaders bool         // Use api-key header instead of Authorization: Bearer
+	mu              sync.RWMutex // Protect useAzureHeaders
 }
 
+
+
 type Option func(*Provider)
 
 const defaultRequestTimeout = common.DefaultRequestTimeout
@@ -90,6 +96,19 @@ func WithExtraBody(extraBody map[string]any) Option {
 	}
 }
 
+func WithAzureHeaders(use bool) Option {
+	return func(p *Provider) {
+		p.useAzureHeaders = use
+	}
+}
+
+func (p *Provider) SetUseAzureHeaders(use bool) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.useAzureHeaders = use
+}
+
+
 func NewProvider(apiKey, apiBase, proxy string, opts ...Option) *Provider {
 	p := &Provider{
 		apiKey:     apiKey,
@@ -459,7 +478,7 @@ func isNativeSearchHost(apiBase string) bool {
 		return false
 	}
 	host := u.Hostname()
-	return host == "api.openai.com" || strings.HasSuffix(host, ".openai.azure.com")
+	return host == "api.openai.com"
 }
 
 // supportsPromptCacheKey reports whether the given API base is known to
@@ -472,5 +491,5 @@ func supportsPromptCacheKey(apiBase string) bool {
 		return false
 	}
 	host := u.Hostname()
-	return host == "api.openai.com" || strings.HasSuffix(host, ".openai.azure.com")
+	return host == "api.openai.com"
 }
diff --git a/pkg/skills/loader.go b/pkg/skills/loader.go
index d30018e45..bdabd63b8 100644
--- a/pkg/skills/loader.go
+++ b/pkg/skills/loader.go
@@ -59,10 +59,10 @@ func (info SkillInfo) validate() error {
 }
 
 type SkillsLoader struct {
-	workspace       string
-	workspaceSkills string // workspace skills (project-level)
-	globalSkills    string // global skills (~/.picoclaw/skills)
-	builtinSkills   string // builtin skills
+	workspace        string
+	workspaceSkills  string // workspace skills (project-level)
+	globalSkills     string // global skills (~/.picoclaw/skills)
+	builtinSkills    string // builtin skills
 	whitelist        []string
 	whitelistEnabled bool
 }
@@ -90,13 +90,19 @@ func (sl *SkillsLoader) SkillRoots() []string {
 	return out
 }
 
-func NewSkillsLoader(workspace string, globalSkills string, builtinSkills string, whitelist []string, whitelistEnabled bool) *SkillsLoader {
+func NewSkillsLoader(
+	workspace string,
+	globalSkills string,
+	builtinSkills string,
+	whitelist []string,
+	whitelistEnabled bool,
+) *SkillsLoader {
 	return &SkillsLoader{
-		workspace:       workspace,
-		workspaceSkills: filepath.Join(workspace, "skills"),
-		globalSkills:    globalSkills, // ~/.picoclaw/skills
-		builtinSkills:   builtinSkills,
-		whitelist:       whitelist,
+		workspace:        workspace,
+		workspaceSkills:  filepath.Join(workspace, "skills"),
+		globalSkills:     globalSkills, // ~/.picoclaw/skills
+		builtinSkills:    builtinSkills,
+		whitelist:        whitelist,
 		whitelistEnabled: whitelistEnabled,
 	}
 }
@@ -196,7 +202,7 @@ func (sl *SkillsLoader) LoadSkill(name string) (string, bool) {
 			return sl.stripFrontmatter(string(content)), true
 		}
 	}
-// ...
+	// ...
 
 	// 2. then load from global skills (~/.picoclaw/skills)
 	if sl.globalSkills != "" {
diff --git a/pkg/skills/loader_test.go b/pkg/skills/loader_test.go
index 69d8b99db..4d0610160 100644
--- a/pkg/skills/loader_test.go
+++ b/pkg/skills/loader_test.go
@@ -417,6 +417,7 @@ func TestGetSkillMetadata_IgnoresHTMLCommentBlocks(t *testing.T) {
 	assert.Equal(t, "biomed-skill", meta.Name)
 	assert.Equal(t, "Summarize biomedical papers.", meta.Description)
 }
+
 func TestListSkillsWithWhitelist(t *testing.T) {
 	tmp := t.TempDir()
 	ws := filepath.Join(tmp, "workspace")
diff --git a/pkg/tools/skills_install.go b/pkg/tools/skills_install.go
index 77eb44655..562809803 100644
--- a/pkg/tools/skills_install.go
+++ b/pkg/tools/skills_install.go
@@ -26,13 +26,18 @@ type InstallSkillTool struct {
 // NewInstallSkillTool creates a new InstallSkillTool.
 // registryMgr is the shared registry manager (same instance as FindSkillsTool).
 // workspace is the root workspace directory; skills install to {workspace}/skills/{slug}/.
-func NewInstallSkillTool(registryMgr *skills.RegistryManager, workspace string, whitelist []string, whitelistEnabled bool) *InstallSkillTool {
+func NewInstallSkillTool(
+	registryMgr *skills.RegistryManager,
+	workspace string,
+	whitelist []string,
+	whitelistEnabled bool,
+) *InstallSkillTool {
 	return &InstallSkillTool{
-		registryMgr: registryMgr,
-		workspace:   workspace,
-		whitelist:   whitelist,
+		registryMgr:      registryMgr,
+		workspace:        workspace,
+		whitelist:        whitelist,
 		whitelistEnabled: whitelistEnabled,
-		mu:          sync.Mutex{},
+		mu:               sync.Mutex{},
 	}
 }
 
diff --git a/pkg/tools/skills_install_test.go b/pkg/tools/skills_install_test.go
index 4d90b7fcc..5c12f0029 100644
--- a/pkg/tools/skills_install_test.go
+++ b/pkg/tools/skills_install_test.go
@@ -102,6 +102,7 @@ func TestInstallSkillToolMissingRegistry(t *testing.T) {
 	assert.True(t, result.IsError)
 	assert.Contains(t, result.ForLLM, "invalid registry")
 }
+
 func TestInstallSkillToolWhitelist(t *testing.T) {
 	workspace := t.TempDir()
 	rm := skills.NewRegistryManager()
diff --git a/pkg/tools/skills_search.go b/pkg/tools/skills_search.go
index bf5c8e8e9..f4d440bc7 100644
--- a/pkg/tools/skills_search.go
+++ b/pkg/tools/skills_search.go
@@ -19,7 +19,12 @@ type FindSkillsTool struct {
 // NewFindSkillsTool creates a new FindSkillsTool.
 // registryMgr is the shared registry manager (built from config in createToolRegistry).
 // cache is the search cache for deduplicating similar queries.
-func NewFindSkillsTool(registryMgr *skills.RegistryManager, cache *skills.SearchCache, whitelist []string, enabled bool) *FindSkillsTool {
+func NewFindSkillsTool(
+	registryMgr *skills.RegistryManager,
+	cache *skills.SearchCache,
+	whitelist []string,
+	enabled bool,
+) *FindSkillsTool {
 	return &FindSkillsTool{
 		registryMgr: registryMgr,
 		cache:       cache,
@@ -98,7 +103,6 @@ func (t *FindSkillsTool) Execute(ctx context.Context, args map[string]any) *Tool
 		results = filtered
 	}
 
-
 	// Cache the results.
 	if t.cache != nil && len(results) > 0 {
 		t.cache.Put(query, results)
diff --git a/web/Makefile b/web/Makefile
index 891c170c2..2db6fb05f 100644
--- a/web/Makefile
+++ b/web/Makefile
@@ -106,10 +106,14 @@ build-dev-picoclaw:
 	@mkdir -p "$$(dirname "$(PICOCLAW_BINARY)")"
 	@$(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o "$(PICOCLAW_BINARY)" ../cmd/picoclaw
 
-# Run all tests
 test:
 	cd $(BACKEND_DIR) && ${WEB_GO} test ./...
-	cd $(FRONTEND_DIR) && pnpm lint
+	@if command -v pnpm >/dev/null 2>&1; then \
+		cd $(FRONTEND_DIR) && pnpm lint; \
+	else \
+		echo "pnpm not found, skipping frontend linting"; \
+	fi
+
 
 # Lint and format
 lint:
diff --git a/web/backend/api/models.go b/web/backend/api/models.go
index e6749b56e..dba52c654 100644
--- a/web/backend/api/models.go
+++ b/web/backend/api/models.go
@@ -130,8 +130,12 @@ func (h *Handler) handleAddModel(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if mc.APIKey != "" {
-		mc.ModelConfig.SetAPIKey(mc.APIKey)
+	apiKey := mc.APIKey
+	if apiKey == "" {
+		apiKey = mc.ModelConfig.APIKey()
+	}
+	if apiKey != "" {
+		mc.ModelConfig.SetAPIKey(apiKey)
 	}
 
 	cfg, err := config.LoadConfig(h.configPath)
@@ -201,13 +205,15 @@ func (h *Handler) handleUpdateModel(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Preserve the existing API key when the caller omits it (empty string).
-	// This lets the UI update api_base / proxy without clearing the stored secret.
-	if mc.APIKey == "" {
-		mc.ModelConfig.SetAPIKey(cfg.ModelList[idx].APIKey())
-	} else {
-		mc.ModelConfig.SetAPIKey(mc.APIKey)
+	apiKey := mc.APIKey
+	if apiKey == "" {
+		apiKey = mc.ModelConfig.APIKey()
 	}
+	if apiKey == "" {
+		apiKey = cfg.ModelList[idx].APIKey()
+	}
+	mc.ModelConfig.SetAPIKey(apiKey)
+
 	// Preserve existing ExtraBody when omitted (nil), but clear it when
 	// the frontend sends an empty object {} to indicate the field should
 	// be removed.
diff --git a/web/backend/api/skills.go b/web/backend/api/skills.go
index 2c054c41b..56cb155b7 100644
--- a/web/backend/api/skills.go
+++ b/web/backend/api/skills.go
@@ -507,6 +507,8 @@ func newSkillsLoader(workspace string) *skills.SkillsLoader {
 		workspace,
 		filepath.Join(globalConfigDir(), "skills"),
 		builtinSkillsDir(),
+		nil,
+		false,
 	)
 }
 

From d4e329f703b3052cdd66653a847dbece69b35959 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Wed, 25 Mar 2026 08:43:34 +0100
Subject: [PATCH 05/25] made /chat asynchronous

---
 README.md            |   1 +
 docs/api.md          |  86 +++++++++++++++++++
 pkg/health/server.go | 197 ++++++++++++++++++++++++++++++++++++-------
 3 files changed, 252 insertions(+), 32 deletions(-)
 create mode 100644 docs/api.md

diff --git a/README.md b/README.md
index a48a53d47..09aebcdff 100644
--- a/README.md
+++ b/README.md
@@ -609,6 +609,7 @@ For detailed guides beyond this README:
 | [SubTurn](docs/subturn.md) | Subagent coordination, concurrency control, lifecycle |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
 | [Tools Configuration](docs/tools_configuration.md) | Per-tool enable/disable, exec policies, MCP, Skills |
+| [Gateway API Reference](docs/api.md) | HTTP endpoints: `/chat`, `/health`, `/ready`, `/reload` |
 | [Hardware Compatibility](docs/hardware-compatibility.md) | Tested boards, minimum requirements |
 
 ## 🤝 Contribute & Roadmap
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 000000000..af59081cd
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,86 @@
+# 🌐 Gateway HTTP API Reference
+
+The PicoClaw gateway provides several HTTP endpoints for health monitoring, management, and direct chat interaction.
+
+By default, the gateway listens on `127.0.0.1:18790`.
+
+## 💬 Chat API
+
+The `/chat` (and alias `/cgat`) endpoint allows you to interact with the PicoClaw agent via a simple HTTP interface. This API is designed to be **asynchronous** to avoid timeouts during long-running LLM tasks or tool executions.
+
+### 1. Initiate a Chat Session (POST)
+
+Start a new chat request.
+
+**Endpoint:** `POST /chat` (or `POST /cgat`)  
+**Content-Type:** `application/json`
+
+**Request Body:**
+```json
+{
+  "message": "What is the capital of France?",
+  "session_id": "optional-custom-id"
+}
+```
+
+**Response (202 Accepted):**
+```json
+{
+  "session_id": "chat-1711352400000",
+  "status": "pending"
+}
+```
+
+### 2. Poll for Results (GET)
+
+Retrieve the status and response of a previously initiated session.
+
+**Endpoint:** `GET /chat?session_id=<ID>` (or `GET /cgat?session_id=<ID>`)
+
+**Possible Responses:**
+
+*   **Still processing (200 OK):**
+    ```json
+    {
+      "session_id": "chat-123",
+      "status": "pending"
+    }
+    ```
+
+*   **Completed (200 OK):**
+    ```json
+    {
+      "session_id": "chat-123",
+      "status": "completed",
+      "response": "The capital of France is Paris."
+    }
+    ```
+
+*   **Error (500 Internal Server Error):**
+    ```json
+    {
+      "session_id": "chat-123",
+      "status": "error",
+      "error": "LLM call failed: context deadline exceeded"
+    }
+    ```
+
+### 💾 Data Persistence & Cleanup
+- **Expiry:** Completed or failed results are kept for **1 hour**. Pending sessions are kept for **2 hours**.
+- **In-Memory:** Results are stored in memory and are lost if the gateway process is restarted.
+
+---
+
+## 🛠️ Management Endpoints
+
+### Health Check
+`GET /health`  
+Returns `OK` (200) if the server is running. Used for basic uptime monitoring.
+
+### Readiness Check
+`GET /ready`  
+Returns `OK` (200) once the gateway and all enabled channels have successfully initialized.
+
+### Configuration Reload
+`POST /reload`  
+Triggers a hot-reload of the `.picoclaw/config.json` file without restarting the process.
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 62c1b606b..4eea0118f 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -19,23 +19,37 @@ type ChatRequest struct {
 	SessionID string `json:"session_id,omitempty"`
 }
 
-// ChatResponse is the JSON response from POST /chat.
+// ChatResponse is the JSON response from /chat.
 type ChatResponse struct {
-	Response string `json:"response"`
+	Response  string `json:"response,omitempty"`
+	SessionID string `json:"session_id,omitempty"`
+	Status    string `json:"status,omitempty"`
+	Error     string `json:"error,omitempty"`
+}
+
+type chatStatus struct {
+	Response  string
+	Error     error
+	Done      bool
+	CreatedAt time.Time
 }
 
 type Server struct {
-	server     *http.Server
-	mu         sync.RWMutex
-	ready      bool
-	checks     map[string]Check
-	startTime  time.Time
-	reloadFunc func() error
-	authToken  string // optional bearer token for protected endpoints
-	chatFunc   func(ctx context.Context, message, sessionID string) (string, error)
-	apiKey     string
+
+	server        *http.Server
+	mu            sync.RWMutex
+	ready         bool
+	checks        map[string]Check
+	startTime     time.Time
+	reloadFunc    func() error
+	authToken     string // optional bearer token for protected endpoints
+	chatFunc      func(ctx context.Context, message, sessionID string) (string, error)
+	apiKey        string
+	chatResults   map[string]*chatStatus
+	chatResultsMu sync.RWMutex
 }
 
+
 type Check struct {
 	Name      string    `json:"name"`
 	Status    string    `json:"status"`
@@ -53,16 +67,21 @@ type StatusResponse struct {
 func NewServer(host string, port int, token string) *Server {
 	mux := http.NewServeMux()
 	s := &Server{
-		ready:     false,
-		checks:    make(map[string]Check),
-		startTime: time.Now(),
-		authToken: token,
+		ready:       false,
+		checks:      make(map[string]Check),
+		startTime:   time.Now(),
+		authToken:   token,
+		chatResults: make(map[string]*chatStatus),
 	}
 
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
 	mux.HandleFunc("/reload", s.reloadHandler)
 	mux.HandleFunc("/chat", s.chatHandler)
+	mux.HandleFunc("/cgat", s.chatHandler)
+
+	// Start task cleanup goroutine
+	go s.taskCleanupLoop()
 
 	addr := fmt.Sprintf("%s:%d", host, port)
 	s.server = &http.Server{
@@ -256,29 +275,40 @@ func (s *Server) RegisterOnMux(mux *http.ServeMux) {
 	mux.HandleFunc("/ready", s.readyHandler)
 	mux.HandleFunc("/reload", s.reloadHandler)
 	mux.HandleFunc("/chat", s.chatHandler)
+	mux.HandleFunc("/cgat", s.chatHandler)
 	mux.HandleFunc("/v1/chat/completions", func(w http.ResponseWriter, r *http.Request) {
 		logger.Error("GATEWAY IS HITTING ITSELF FOR LLM CALLS!")
 		http.Error(w, "GATEWAY LOOP DETECTION", http.StatusLoopDetected)
 	})
 }
 
-// chatHandler handles POST /chat — a synchronous HTTP chat API.
-// Request body:  {"message": "...", "session_id": "..." (optional)}
-// Response body: {"response": "..."}
+// chatHandler handles POST /chat (initiate async) and GET /chat (poll for result).
+// POST body: {"message": "...", "session_id": "..." (optional)}
+// POST response: {"session_id": "...", "status": "pending"}
+// GET query: ?session_id=...
+// GET response: {"response": "...", "status": "completed"}
 func (s *Server) chatHandler(w http.ResponseWriter, r *http.Request) {
 	if !s.verifyAPIKey(r) {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusUnauthorized)
-		json.NewEncoder(w).Encode(map[string]string{"error": "unauthorized"})
-		return
-	}
-	if r.Method != http.MethodPost {
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusMethodNotAllowed)
-		json.NewEncoder(w).Encode(map[string]string{"error": "method not allowed, use POST"})
+		json.NewEncoder(w).Encode(ChatResponse{Error: "unauthorized"})
 		return
 	}
 
+	if r.Method == http.MethodPost {
+		s.handlePostChat(w, r)
+		return
+	} else if r.Method == http.MethodGet {
+		s.handleGetChat(w, r)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusMethodNotAllowed)
+	json.NewEncoder(w).Encode(ChatResponse{Error: "method not allowed, use POST or GET"})
+}
+
+func (s *Server) handlePostChat(w http.ResponseWriter, r *http.Request) {
 	s.mu.RLock()
 	chatFunc := s.chatFunc
 	s.mu.RUnlock()
@@ -286,7 +316,7 @@ func (s *Server) chatHandler(w http.ResponseWriter, r *http.Request) {
 	if chatFunc == nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusServiceUnavailable)
-		json.NewEncoder(w).Encode(map[string]string{"error": "chat not configured"})
+		json.NewEncoder(w).Encode(ChatResponse{Error: "chat not configured"})
 		return
 	}
 
@@ -294,27 +324,130 @@ func (s *Server) chatHandler(w http.ResponseWriter, r *http.Request) {
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusBadRequest)
-		json.NewEncoder(w).Encode(map[string]string{"error": "invalid JSON: " + err.Error()})
+		json.NewEncoder(w).Encode(ChatResponse{Error: "invalid JSON: " + err.Error()})
 		return
 	}
 	if req.Message == "" {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusBadRequest)
-		json.NewEncoder(w).Encode(map[string]string{"error": "message field is required"})
+		json.NewEncoder(w).Encode(ChatResponse{Error: "message field is required"})
 		return
 	}
 
-	reply, err := chatFunc(r.Context(), req.Message, req.SessionID)
-	if err != nil {
+	sessionID := req.SessionID
+	if sessionID == "" {
+		sessionID = fmt.Sprintf("chat-%d", time.Now().UnixNano())
+	}
+
+	// Initialize status
+	s.chatResultsMu.Lock()
+	s.chatResults[sessionID] = &chatStatus{
+		CreatedAt: time.Now(),
+	}
+	s.chatResultsMu.Unlock()
+
+	// Start processing in background
+	go func() {
+		// Use a long-running context for the chat call, but don't bind to r.Context()
+		// which will be cancelled when this request finishes.
+		ctx := context.Background()
+		logger.Debugf("Starting async chat for session %s", sessionID)
+		reply, err := chatFunc(ctx, req.Message, sessionID)
+
+		s.chatResultsMu.Lock()
+		defer s.chatResultsMu.Unlock()
+		if result, ok := s.chatResults[sessionID]; ok {
+			result.Response = reply
+			result.Error = err
+			result.Done = true
+			logger.Debugf("Finished async chat for session %s (err=%v)", sessionID, err)
+		}
+	}()
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusAccepted)
+	json.NewEncoder(w).Encode(ChatResponse{
+		SessionID: sessionID,
+		Status:    "pending",
+	})
+}
+
+func (s *Server) handleGetChat(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.URL.Query().Get("session_id")
+	if sessionID == "" {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(ChatResponse{Error: "session_id query parameter is required"})
+		return
+	}
+
+	s.chatResultsMu.RLock()
+	result, ok := s.chatResults[sessionID]
+	if !ok {
+		s.chatResultsMu.RUnlock()
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusNotFound)
+		json.NewEncoder(w).Encode(ChatResponse{Error: "session not found"})
+		return
+	}
+
+	// Read fields while holding the lock to avoid race conditions
+	done := result.Done
+	response := result.Response
+	errVal := result.Error
+	s.chatResultsMu.RUnlock()
+
+	if !done {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		json.NewEncoder(w).Encode(ChatResponse{
+			SessionID: sessionID,
+			Status:    "pending",
+		})
+		return
+	}
+
+	if errVal != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusInternalServerError)
-		json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
+		json.NewEncoder(w).Encode(ChatResponse{
+			SessionID: sessionID,
+			Status:    "error",
+			Error:     errVal.Error(),
+		})
 		return
 	}
 
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
-	json.NewEncoder(w).Encode(ChatResponse{Response: reply})
+	json.NewEncoder(w).Encode(ChatResponse{
+		SessionID: sessionID,
+		Status:    "completed",
+		Response:  response,
+	})
+}
+
+func (s *Server) taskCleanupLoop() {
+	ticker := time.NewTicker(10 * time.Minute)
+	defer ticker.Stop()
+
+	for range ticker.C {
+		s.chatResultsMu.Lock()
+		now := time.Now()
+		for id, status := range s.chatResults {
+			// Keep pending tasks for 2 hours, completed/error for 1 hour
+			expiry := time.Hour
+			if !status.Done {
+				expiry = 2 * time.Hour
+			}
+
+			if now.Sub(status.CreatedAt) > expiry {
+				delete(s.chatResults, id)
+				logger.Debugf("Cleaned up expired chat session %s", id)
+			}
+		}
+		s.chatResultsMu.Unlock()
+	}
 }
 
 func statusString(ok bool) string {

From 46df3807d83ea704f87575c7bb93aed0038b6bf2 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Wed, 25 Mar 2026 08:53:59 +0100
Subject: [PATCH 06/25] chore: remove runtime state from tracking

---
 workspace/heartbeat.log    | 1 -
 workspace/state/state.json | 4 ----
 2 files changed, 5 deletions(-)
 delete mode 100644 workspace/heartbeat.log
 delete mode 100644 workspace/state/state.json

diff --git a/workspace/heartbeat.log b/workspace/heartbeat.log
deleted file mode 100644
index 8fb65ced5..000000000
--- a/workspace/heartbeat.log
+++ /dev/null
@@ -1 +0,0 @@
-[2026-03-24 08:15:50] [INFO] Created default HEARTBEAT.md template
diff --git a/workspace/state/state.json b/workspace/state/state.json
deleted file mode 100644
index 912b9bc59..000000000
--- a/workspace/state/state.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "last_channel": "telegram:8271300679",
-  "timestamp": "2026-03-24T08:43:14.295101255+01:00"
-}
\ No newline at end of file

From 1bb3ca49abc08808ea4eb9a52422b0201c0152b9 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Thu, 26 Mar 2026 07:19:38 +0100
Subject: [PATCH 07/25] made paths relative to workspace for sub-agents

---
 pkg/agent/context.go | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index 2666faf91..09b649761 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -104,6 +104,8 @@ Your workspace is at: %s
 
 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.
 
+5. **Path Resolution** - ALWAYS use paths relative to your workspace root (e.g., "relay_project/go.mod"). DO NOT start paths with a leading slash ("/") or use absolute paths, as they are blocked for security.
+
 %s`,
 		version, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath, toolDiscovery)
 }

From 5913149664989b411a924c328783eb4ed1bce37f Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Thu, 26 Mar 2026 19:34:16 +0100
Subject: [PATCH 08/25] fix(agent): ensure isolated agents inherit manually
 registered tools to prevent test hangs

---
 Makefile                                |   2 +-
 cmd/picoclaw/internal/skills/command.go |   2 +-
 docs/configuration.md                   |  91 +++++++++---------
 pkg/agent/context.go                    |  22 ++++-
 pkg/agent/context_cache_test.go         |  28 +++---
 pkg/agent/definition.go                 |  20 +++-
 pkg/agent/definition_test.go            |  16 ++--
 pkg/agent/eventbus_test.go              |   2 +-
 pkg/agent/instance.go                   |  37 ++++---
 pkg/agent/instance_test.go              |  40 ++++++--
 pkg/agent/isolation_tools_test.go       | 122 ++++++++++++++++++++++++
 pkg/agent/loop.go                       | 105 ++++++++++++++++++--
 pkg/agent/loop_mcp.go                   |   2 +-
 pkg/agent/loop_test.go                  |  11 +--
 pkg/agent/registry.go                   |   5 +-
 pkg/agent/steering_test.go              |  26 ++---
 pkg/gateway/gateway.go                  |   7 +-
 pkg/health/server.go                    |  57 ++++++++++-
 pkg/skills/loader.go                    |  40 +++++---
 pkg/skills/loader_test.go               |  26 ++---
 web/backend/api/skills.go               |   1 +
 21 files changed, 507 insertions(+), 155 deletions(-)
 create mode 100644 pkg/agent/isolation_tools_test.go

diff --git a/Makefile b/Makefile
index 42e6c299b..5f8c26e1a 100644
--- a/Makefile
+++ b/Makefile
@@ -268,7 +268,7 @@ vet: generate
 
 ## test: Test Go code
 test: generate
-	@$(GO) test $(GOFLAGS) $$($(GO) list $(GOFLAGS) ./... | grep -v github.com/sipeed/picoclaw/web/)
+	@$(GO) test $(GOFLAGS) -p 1 $$($(GO) list $(GOFLAGS) ./... | grep -v github.com/sipeed/picoclaw/web/) -timeout 120s
 	@cd web && make test
 
 ## fmt: Format Go code
diff --git a/cmd/picoclaw/internal/skills/command.go b/cmd/picoclaw/internal/skills/command.go
index 4df257140..19caca9ec 100644
--- a/cmd/picoclaw/internal/skills/command.go
+++ b/cmd/picoclaw/internal/skills/command.go
@@ -43,7 +43,7 @@ func NewSkillsCommand() *cobra.Command {
 			globalDir := filepath.Dir(internal.GetConfigPath())
 			globalSkillsDir := filepath.Join(globalDir, "skills")
 			builtinSkillsDir := filepath.Join(globalDir, "picoclaw", "skills")
-			d.skillsLoader = skills.NewSkillsLoader(d.workspace, globalSkillsDir, builtinSkillsDir, nil, false)
+			d.skillsLoader = skills.NewSkillsLoader(d.workspace, d.workspace, globalSkillsDir, builtinSkillsDir, nil, false)
 
 			return nil
 		},
diff --git a/docs/configuration.md b/docs/configuration.md
index 7a5902f58..e94374160 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -6,8 +6,6 @@
 
 Config file: `~/.picoclaw/config.json`
 
-> **Security Configuration:** For storing API keys, tokens, and other sensitive data, see the [Security Configuration Guide](security_configuration.md).
-
 ### Environment Variables
 
 You can override default paths using environment variables. This is useful for portable installations, containerized deployments, or running picoclaw as a system service. These variables are independent and control different paths.
@@ -40,12 +38,12 @@ PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gat
 ```json
 {
   "gateway": {
-    "log_level": "warn"
+    "log_level": "fatal"
   }
 }
 ```
 
-When omitted, the default is `warn`. Supported values: `debug`, `info`, `warn`, `error`, `fatal`.
+When omitted, the default is `fatal`. Supported values: `debug`, `info`, `warn`, `error`, `fatal`.
 
 You can also override this with the environment variable `PICOCLAW_LOG_LEVEL`.
 
@@ -69,18 +67,38 @@ PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspa
 
 > **Note:** Changes to `AGENT.md`, `SOUL.md`, `USER.md` and `memory/MEMORY.md` are automatically detected at runtime via file modification time (mtime) tracking. You do **not** need to restart the gateway after editing these files — the agent picks up the new content on the next request.
 
-### Web launcher dashboard
-
-**picoclaw-launcher** serves a browser UI that requires sign-in first. By default, the **dashboard token** and **session signing key** are **generated in memory on each start** (a new random token after every restart). Set **`PICOCLAW_LAUNCHER_TOKEN`** to pin a fixed token for that process (startup logs do not print the secret when this env var is used).
-
-**Where to read the token**: In **console mode** (`-console`), it is printed at startup. In **tray / GUI mode**, use the tray action **Copy dashboard token**, and check **`$PICOCLAW_HOME/logs/launcher.log`** (typically `~/.picoclaw/logs/launcher.log` if `PICOCLAW_HOME` is unset) for the random token logged on startup. The login page shows hints that match how the launcher is running (including the absolute log path); **responses do not include the token itself**.
-
-- **Config file**: Same directory as `config.json` (or the file pointed to by `PICOCLAW_CONFIG`). The launcher-specific file is `launcher-config.json`.
-- **Sign-in and links**: Enter the token on the login page, or open with `?token=` when the browser is launched automatically. All responses include **`Referrer-Policy: no-referrer`** to reduce leakage of `token` via the `Referer` header.
-- **Sign-out**: Use **`POST /api/auth/logout`** with **`Content-Type: application/json`** (body may be `{}`). Do not rely on a GET URL for logout (CSRF-safe pattern).
-- **Brute-force**: **`POST /api/auth/login`** is **rate-limited per client IP per minute** (HTTP 429 when exceeded).
-- **Session lifetime**: The HttpOnly session cookie lasts about **7 days** by default; sign in again with the token after it expires.
-
+### 🔒 Multi-Tenant Agent Isolation
+ 
+PicoClaw supports safe multi-tenancy on shared infrastructure (e.g., Azure deployments). It dynamically isolates each chat session into its own private sub-workspace to prevent data collisions and ensure privacy between different users/callers (like n8n, Foundation Agents, etc.).
+ 
+#### Isolation Strategy
+ 
+When an incoming message includes a **ChatID** (passed in the `/chat` API or extracted from internal channels), PicoClaw automatically activates **Tenant Isolation**:
+ 
+1.  **Isolated Workspace:** The agent's operations are restricted to `workspace/sessions/{isolationID}/workspace`.
+2.  **Isolated Memory:** Long-term memory (`MEMORY.md`) is stored and read from the isolated session path.
+3.  **Isolated Tools:** Tools like `read_file` and `write_file` are automatically pointed to the isolated workspace, preventing any tenant from accessing another's files or the global base workspace.
+ 
+#### Tenant Identification (Inbound Integration)
+ 
+PicoClaw automatically detects the **ChatID** for isolation from several sources:
+ 
+1.  **API Headers (Automatic):** It checks for common tenant-identifying headers from API Gateways:
+    - `X-PicoClaw-Chat-ID`: Custom header for manual control.
+    - `Ocp-Apim-Subscription-Id`: Automatically captures the **Azure APIM Subscription ID** as the tenant identifier.
+2.  **API Body:** The JSON payload for `/chat` can include a `chat_id` (or `session_id`) field.
+3.  **Channel Context:** Channels like Microsoft Teams, Telegram, and Discord automatically pass their respective `ChatID`.
+ 
+**What happens if no ID is present?**
+If no `ChatID` is detected, the request is routed to the **Global Agent** context, which uses the root workspace. This is the default for standalone single-user deployments. For secure multi-tenancy on shared infrastructure, ensuring a persistent `ChatID` is passed from your API Gateway or client is highly recommended.
+ 
+#### Path Resolution
+ 
+-   **Global Agents:** Agents initialized at startup (without a specific session) use the root workspace.
+-   **Session Agents:** Every request with a `chatID` creates a transient isolated agent instance that "routes" all file and memory operations into its session-specific subdirectory.
+ 
+This mechanism is transparent to the end-user and the AI agent itself, ensuring a secure and portable multi-user environment out-of-the-box.
+ 
 ### Skill Sources
 
 By default, skills are loaded from:
@@ -541,9 +559,8 @@ This design also enables **multi-agent support** with flexible provider selectio
 
 - **Different agents, different providers**: Each agent can use its own LLM provider
 - **Model fallbacks**: Configure primary and fallback models for resilience
-- **Load balancing**: Distribute requests across multiple endpoints or keys
+- **Load balancing**: Distribute requests across multiple endpoints
 - **Centralized configuration**: Manage all providers in one place
-- **Model enable/disable**: Use the `enabled` field to temporarily disable a model without removing its configuration
 
 #### 🔒 Security Configuration (Recommended)
 
@@ -623,7 +640,6 @@ For complete documentation, see [`security_configuration.md`](security_configura
 | **通义千问 (Qwen)**     | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
 | **NVIDIA**              | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
 | **Ollama**              | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
-| **LM Studio**           | `lmstudio/`       | `http://localhost:1234/v1`                          | OpenAI    | Optional (local default: no key)                                 |
 | **OpenRouter**          | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
 | **LiteLLM Proxy**       | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | Your LiteLLM proxy key                                           |
 | **VLLM**                | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
@@ -645,22 +661,22 @@ For complete documentation, see [`security_configuration.md`](security_configura
     {
       "model_name": "ark-code-latest",
       "model": "volcengine/ark-code-latest",
-      "api_keys": ["sk-your-api-key"]
+      "api_key": "sk-your-api-key"
     },
     {
       "model_name": "gpt-5.4",
       "model": "openai/gpt-5.4",
-      "api_keys": ["sk-your-openai-key"]
+      "api_key": "sk-your-openai-key"
     },
     {
       "model_name": "claude-sonnet-4.6",
       "model": "anthropic/claude-sonnet-4.6",
-      "api_keys": ["sk-ant-your-key"]
+      "api_key": "sk-ant-your-key"
     },
     {
       "model_name": "glm-4.7",
       "model": "zhipu/glm-4.7",
-      "api_keys": ["your-zhipu-key"]
+      "api_key": "your-zhipu-key"
     }
   ],
   "agents": {
@@ -671,9 +687,7 @@ For complete documentation, see [`security_configuration.md`](security_configura
 }
 ```
 
-> **Security Note**: You can remove `api_keys` fields from your config and store them in `.security.yml` instead. See [Security Configuration](#-security-configuration-recommended) above for details.
->
-> **Note**: The `enabled` field can be set to `false` to disable a model entry without removing it. When omitted, it defaults to `true` during migration for models that have API keys.
+> **Security Note**: You can remove `api_key` fields from your config and store them in `.security.yml` instead. See [Security Configuration](#-security-configuration-recommended) above for details.
 
 #### Vendor-Specific Examples
 
@@ -750,7 +764,7 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 {
   "model_name": "claude-opus-4-6",
   "model": "anthropic-messages/claude-opus-4-6",
-  "api_keys": ["sk-ant-your-key"],
+  "api_key": "sk-ant-your-key",
   "api_base": "https://api.anthropic.com"
 }
 ```
@@ -771,21 +785,6 @@ For direct Anthropic API access or custom endpoints that only support Anthropic'
 
 </details>
 
-<details>
-<summary><b>LM Studio (local)</b></summary>
-
-```json
-{
-  "model_name": "lmstudio-local",
-  "model": "lmstudio/openai/gpt-oss-20b"
-}
-```
-
-`api_base` defaults to `http://localhost:1234/v1`. API key is optional unless your LM Studio server enables authentication.<br/>
-PicoClaw sends OpenAI-compatible requests to LM Studio, and strips the `lmstudio/` prefix before sending requests, so `lmstudio/openai/gpt-oss-20b` sends `openai/gpt-oss-20b` to the LM Studio server.
-
-</details>
-
 <details>
 <summary><b>Custom Proxy / LiteLLM</b></summary>
 
@@ -840,13 +839,13 @@ model_list:
       "model_name": "gpt-5.4",
       "model": "openai/gpt-5.4",
       "api_base": "https://api1.example.com/v1",
-      "api_keys": ["sk-key1"]
+      "api_key": "sk-key1"
     },
     {
       "model_name": "gpt-5.4",
       "model": "openai/gpt-5.4",
       "api_base": "https://api2.example.com/v1",
-      "api_keys": ["sk-key2"]
+      "api_key": "sk-key2"
     }
   ]
 }
@@ -854,7 +853,7 @@ model_list:
 
 #### Migration from Legacy `providers` Config
 
-The old `providers` configuration is **deprecated** and has been removed in V2. Existing V0/V1 configs are auto-migrated. See [docs/migration/model-list-migration.md](../migration/model-list-migration.md) for the full guide.
+The old `providers` configuration is **deprecated** but still supported for backward compatibility. See [docs/migration/model-list-migration.md](../migration/model-list-migration.md) for the full guide.
 
 ### Provider Architecture
 
@@ -864,7 +863,7 @@ PicoClaw routes providers by protocol family:
 - **Anthropic**: Claude-native API behavior.
 - **Codex/OAuth**: OpenAI OAuth/token authentication route.
 
-This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_keys`).
+This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
 
 <details>
 <summary><b>Zhipu (legacy providers format)</b></summary>
diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index 09b649761..3975a6da7 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -21,6 +21,7 @@ import (
 
 type ContextBuilder struct {
 	workspace          string
+	baseWorkspace      string
 	skillsLoader       *skills.SkillsLoader
 	memory             *MemoryStore
 	toolDiscoveryBM25  bool
@@ -61,7 +62,11 @@ func getGlobalConfigDir() string {
 	return config.GetHome()
 }
 
-func NewContextBuilder(workspace string) *ContextBuilder {
+func NewContextBuilder(workspace string, baseWorkspace string) *ContextBuilder {
+	// If isolationID logic is needed, it should be handled by the caller
+	// ensuring workspace and baseWorkspace are correctly distinct.
+	os.MkdirAll(workspace, 0o755)
+
 	// builtin skills: skills directory in current project
 	// Use the skills/ directory under the current working directory
 	builtinSkillsDir := strings.TrimSpace(os.Getenv(config.EnvBuiltinSkills))
@@ -72,9 +77,10 @@ func NewContextBuilder(workspace string) *ContextBuilder {
 	globalSkillsDir := filepath.Join(getGlobalConfigDir(), "skills")
 
 	return &ContextBuilder{
-		workspace:    workspace,
-		skillsLoader: skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir, nil, false),
-		memory:       NewMemoryStore(workspace),
+		workspace:     workspace,
+		baseWorkspace: baseWorkspace,
+		skillsLoader:  skills.NewSkillsLoader(workspace, baseWorkspace, globalSkillsDir, builtinSkillsDir, nil, false),
+		memory:        NewMemoryStore(workspace),
 	}
 }
 
@@ -462,7 +468,13 @@ func (cb *ContextBuilder) LoadBootstrapFiles() string {
 
 	if agentDefinition.Source != AgentDefinitionSourceAgent {
 		filePath := filepath.Join(cb.workspace, "IDENTITY.md")
-		if data, err := os.ReadFile(filePath); err == nil {
+		data, err := os.ReadFile(filePath)
+		if err != nil && cb.baseWorkspace != "" && cb.baseWorkspace != cb.workspace {
+			// Fallback to base workspace
+			filePath = filepath.Join(cb.baseWorkspace, "IDENTITY.md")
+			data, err = os.ReadFile(filePath)
+		}
+		if err == nil {
 			fmt.Fprintf(&sb, "## %s\n\n%s\n\n", "IDENTITY.md", data)
 		}
 	}
diff --git a/pkg/agent/context_cache_test.go b/pkg/agent/context_cache_test.go
index ef5e6c5de..a2cdf2b54 100644
--- a/pkg/agent/context_cache_test.go
+++ b/pkg/agent/context_cache_test.go
@@ -41,7 +41,7 @@ func TestSingleSystemMessage(t *testing.T) {
 	})
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	tests := []struct {
 		name    string
@@ -132,7 +132,7 @@ func TestBuildMessages_CurrentSenderDynamicContext(t *testing.T) {
 	})
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	tests := []struct {
 		name              string
@@ -221,7 +221,7 @@ func TestMtimeAutoInvalidation(t *testing.T) {
 			tmpDir := setupWorkspace(t, map[string]string{tt.file: tt.contentV1})
 			defer os.RemoveAll(tmpDir)
 
-			cb := NewContextBuilder(tmpDir)
+			cb := NewContextBuilder(tmpDir, tmpDir)
 
 			sp1 := cb.BuildSystemPromptWithCache()
 
@@ -257,7 +257,7 @@ func TestMtimeAutoInvalidation(t *testing.T) {
 		tmpDir := setupWorkspace(t, nil)
 		defer os.RemoveAll(tmpDir)
 
-		cb := NewContextBuilder(tmpDir)
+		cb := NewContextBuilder(tmpDir, tmpDir)
 		_ = cb.BuildSystemPromptWithCache() // populate cache
 
 		// Touch skills directory (simulate new skill installed)
@@ -284,7 +284,7 @@ func TestExplicitInvalidateCache(t *testing.T) {
 	})
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	sp1 := cb.BuildSystemPromptWithCache()
 	cb.InvalidateCache()
@@ -312,7 +312,7 @@ func TestCacheStability(t *testing.T) {
 	})
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	results := make([]string, 5)
 	for i := range results {
@@ -361,7 +361,7 @@ func TestNewFileCreationInvalidatesCache(t *testing.T) {
 			tmpDir := setupWorkspace(t, nil)
 			defer os.RemoveAll(tmpDir)
 
-			cb := NewContextBuilder(tmpDir)
+			cb := NewContextBuilder(tmpDir, tmpDir)
 
 			// Populate cache — file does not exist yet
 			sp1 := cb.BuildSystemPromptWithCache()
@@ -406,7 +406,7 @@ Original content.`
 	})
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	// Populate cache
 	sp1 := cb.BuildSystemPromptWithCache()
@@ -467,7 +467,7 @@ description: global-v1
 		t.Fatal(err)
 	}
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	sp1 := cb.BuildSystemPromptWithCache()
 	if !strings.Contains(sp1, "global-v1") {
 		t.Fatal("expected initial prompt to contain global skill description")
@@ -527,7 +527,7 @@ description: builtin-v1
 		t.Fatal(err)
 	}
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	sp1 := cb.BuildSystemPromptWithCache()
 	if !strings.Contains(sp1, "builtin-v1") {
 		t.Fatal("expected initial prompt to contain builtin skill description")
@@ -574,7 +574,7 @@ description: delete-me-v1
 	})
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	sp1 := cb.BuildSystemPromptWithCache()
 	if !strings.Contains(sp1, "delete-me-v1") {
 		t.Fatal("expected initial prompt to contain skill description")
@@ -614,7 +614,7 @@ func TestConcurrentBuildSystemPromptWithCache(t *testing.T) {
 	})
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	const goroutines = 20
 	const iterations = 50
@@ -677,7 +677,7 @@ func TestEmptyWorkspaceBaselineDetectsNewFiles(t *testing.T) {
 	tmpDir := setupWorkspace(t, nil)
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	// Build cache — all tracked files are absent, maxMtime falls back to epoch.
 	sp1 := cb.BuildSystemPromptWithCache()
@@ -750,7 +750,7 @@ func BenchmarkBuildMessagesWithCache(b *testing.B) {
 		os.WriteFile(filepath.Join(tmpDir, name), []byte(strings.Repeat("Content.\n", 10)), 0o644)
 	}
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	history := []providers.Message{
 		{Role: "user", Content: "previous message"},
 		{Role: "assistant", Content: "previous response"},
diff --git a/pkg/agent/definition.go b/pkg/agent/definition.go
index cf73d607c..1e1dbc8f6 100644
--- a/pkg/agent/definition.go
+++ b/pkg/agent/definition.go
@@ -73,7 +73,25 @@ type AgentContextDefinition struct {
 // structured files are absent, it falls back to the legacy AGENTS.md layout so
 // the current runtime can transition incrementally.
 func (cb *ContextBuilder) LoadAgentDefinition() AgentContextDefinition {
-	return loadAgentDefinition(cb.workspace)
+	def := loadAgentDefinition(cb.workspace)
+	if def.Source == "" && cb.baseWorkspace != "" && cb.baseWorkspace != cb.workspace {
+		// Fallback to base workspace if nothing found in isolated workspace
+		baseDef := loadAgentDefinition(cb.baseWorkspace)
+		if baseDef.Source != "" {
+			// Inherit Agent and Source from base, but keep Tenant's User/Soul if they exist
+			if def.Agent == nil {
+				def.Agent = baseDef.Agent
+				def.Source = baseDef.Source
+			}
+			if def.Soul == nil {
+				def.Soul = baseDef.Soul
+			}
+			if def.User == nil {
+				def.User = baseDef.User
+			}
+		}
+	}
+	return def
 }
 
 func loadAgentDefinition(workspace string) AgentContextDefinition {
diff --git a/pkg/agent/definition_test.go b/pkg/agent/definition_test.go
index 5ee996967..a6a93ea08 100644
--- a/pkg/agent/definition_test.go
+++ b/pkg/agent/definition_test.go
@@ -34,7 +34,7 @@ Act directly and use tools first.
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	definition := cb.LoadAgentDefinition()
 
 	if definition.Source != AgentDefinitionSourceAgent {
@@ -86,7 +86,7 @@ func TestLoadAgentDefinitionFallsBackToLegacyAgentsMarkdown(t *testing.T) {
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	definition := cb.LoadAgentDefinition()
 
 	if definition.Source != AgentDefinitionSourceAgents {
@@ -113,7 +113,7 @@ func TestLoadAgentDefinitionLoadsWorkspaceUserMarkdown(t *testing.T) {
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	definition := cb.LoadAgentDefinition()
 
 	if definition.User == nil {
@@ -142,7 +142,7 @@ Keep going.
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	definition := cb.LoadAgentDefinition()
 
 	if definition.Agent == nil {
@@ -178,7 +178,7 @@ Follow the body prompt.
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	bootstrap := cb.LoadBootstrapFiles()
 
 	if !strings.Contains(bootstrap, "Follow the body prompt") {
@@ -209,7 +209,7 @@ func TestLoadBootstrapFilesIncludesWorkspaceUserMarkdown(t *testing.T) {
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	bootstrap := cb.LoadBootstrapFiles()
 
 	if !strings.Contains(bootstrap, "Shared profile") {
@@ -228,7 +228,7 @@ func TestStructuredAgentIgnoresIdentityChanges(t *testing.T) {
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	promptV1 := cb.BuildSystemPromptWithCache()
 	if strings.Contains(promptV1, "Legacy identity") {
@@ -265,7 +265,7 @@ func TestStructuredAgentUserChangesInvalidateCache(t *testing.T) {
 	})
 	defer cleanupWorkspace(t, tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 
 	promptV1 := cb.BuildSystemPromptWithCache()
 	if !strings.Contains(promptV1, "Initial workspace preferences") {
diff --git a/pkg/agent/eventbus_test.go b/pkg/agent/eventbus_test.go
index 2785d70a5..586bdc84a 100644
--- a/pkg/agent/eventbus_test.go
+++ b/pkg/agent/eventbus_test.go
@@ -275,7 +275,7 @@ func TestAgentLoop_EmitsSteeringAndSkippedToolEvents(t *testing.T) {
 
 	resultCh := make(chan string, 1)
 	go func() {
-		resp, _ := al.ProcessDirectWithChannel(context.Background(), "do something", "test-session", "test", "chat1")
+		resp, _ := al.ProcessDirectWithChannel(context.Background(), "do something", "test-session", "test", "direct")
 		resultCh <- resp
 	}()
 
diff --git a/pkg/agent/instance.go b/pkg/agent/instance.go
index bacfa49c5..73d90dac5 100644
--- a/pkg/agent/instance.go
+++ b/pkg/agent/instance.go
@@ -59,8 +59,9 @@ func NewAgentInstance(
 	defaults *config.AgentDefaults,
 	cfg *config.Config,
 	provider providers.LLMProvider,
+	isolationID string,
 ) *AgentInstance {
-	workspace := resolveAgentWorkspace(agentCfg, defaults)
+	workspace := resolveAgentWorkspace(agentCfg, defaults, isolationID)
 	os.MkdirAll(workspace, 0o755)
 
 	model := resolveAgentModel(agentCfg, defaults)
@@ -107,11 +108,15 @@ func NewAgentInstance(
 		toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict, allowWritePaths))
 	}
 
-	sessionsDir := filepath.Join(workspace, "sessions")
+	// Use main agent workspace (no isolation) for sessions so that session history
+	// persists across transient instances. The isolated workspace is only for file tools.
+	mainWorkspace := resolveOriginalAgentWorkspace(agentCfg, defaults)
+	sessionsDir := filepath.Join(mainWorkspace, "sessions")
 	sessions := initSessionStore(sessionsDir)
 
 	mcpDiscoveryActive := cfg.Tools.MCP.Enabled && cfg.Tools.MCP.Discovery.Enabled
-	contextBuilder := NewContextBuilder(workspace).
+	baseWorkspace := mainWorkspace
+	contextBuilder := NewContextBuilder(workspace, baseWorkspace).
 		WithToolDiscovery(
 			mcpDiscoveryActive && cfg.Tools.MCP.Discovery.UseBM25,
 			mcpDiscoveryActive && cfg.Tools.MCP.Discovery.UseRegex,
@@ -234,17 +239,27 @@ func NewAgentInstance(
 }
 
 // resolveAgentWorkspace determines the workspace directory for an agent.
-func resolveAgentWorkspace(agentCfg *config.AgentConfig, defaults *config.AgentDefaults) string {
+func resolveAgentWorkspace(agentCfg *config.AgentConfig, defaults *config.AgentDefaults, isolationID string) string {
+	base := ""
 	if agentCfg != nil && strings.TrimSpace(agentCfg.Workspace) != "" {
-		return expandHome(strings.TrimSpace(agentCfg.Workspace))
+		base = expandHome(strings.TrimSpace(agentCfg.Workspace))
+	} else if agentCfg == nil || agentCfg.Default || agentCfg.ID == "" || routing.NormalizeAgentID(agentCfg.ID) == "main" {
+		base = expandHome(defaults.Workspace)
+	} else {
+		// For named agents without explicit workspace, use default workspace with agent ID suffix
+		id := routing.NormalizeAgentID(agentCfg.ID)
+		base = filepath.Join(expandHome(defaults.Workspace), "..", "workspace-"+id)
 	}
-	// Use the configured default workspace (respects PICOCLAW_HOME)
-	if agentCfg == nil || agentCfg.Default || agentCfg.ID == "" || routing.NormalizeAgentID(agentCfg.ID) == "main" {
-		return expandHome(defaults.Workspace)
+
+	if isolationID != "" && isolationID != "direct" {
+		return filepath.Join(base, "sessions", isolationID, "workspace")
 	}
-	// For named agents without explicit workspace, use default workspace with agent ID suffix
-	id := routing.NormalizeAgentID(agentCfg.ID)
-	return filepath.Join(expandHome(defaults.Workspace), "..", "workspace-"+id)
+	return base
+}
+
+// resolveOriginalAgentWorkspace determines the original workspace directory for an agent without isolation.
+func resolveOriginalAgentWorkspace(agentCfg *config.AgentConfig, defaults *config.AgentDefaults) string {
+	return resolveAgentWorkspace(agentCfg, defaults, "")
 }
 
 // resolveAgentModel resolves the primary model for an agent.
diff --git a/pkg/agent/instance_test.go b/pkg/agent/instance_test.go
index ba907e88b..93649f8ec 100644
--- a/pkg/agent/instance_test.go
+++ b/pkg/agent/instance_test.go
@@ -33,7 +33,7 @@ func TestNewAgentInstance_UsesDefaultsTemperatureAndMaxTokens(t *testing.T) {
 	cfg.Agents.Defaults.Temperature = &configuredTemp
 
 	provider := &mockProvider{}
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider, "")
 
 	if agent.MaxTokens != 1234 {
 		t.Fatalf("MaxTokens = %d, want %d", agent.MaxTokens, 1234)
@@ -65,7 +65,7 @@ func TestNewAgentInstance_DefaultsTemperatureWhenZero(t *testing.T) {
 	cfg.Agents.Defaults.Temperature = &configuredTemp
 
 	provider := &mockProvider{}
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider, "")
 
 	if agent.Temperature != 0.0 {
 		t.Fatalf("Temperature = %f, want %f", agent.Temperature, 0.0)
@@ -91,7 +91,7 @@ func TestNewAgentInstance_DefaultsTemperatureWhenUnset(t *testing.T) {
 	}
 
 	provider := &mockProvider{}
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider, "")
 
 	if agent.Temperature != 0.7 {
 		t.Fatalf("Temperature = %f, want %f", agent.Temperature, 0.7)
@@ -150,7 +150,7 @@ func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
 			}
 
 			provider := &mockProvider{}
-			agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+			agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider, "")
 
 			if len(agent.Candidates) != 1 {
 				t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
@@ -257,7 +257,7 @@ func TestNewAgentInstance_AllowsMediaTempDirForReadListAndExec(t *testing.T) {
 		},
 	}
 
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{})
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{}, "")
 
 	readTool, ok := agent.Tools.Get("read_file")
 	if !ok {
@@ -361,7 +361,7 @@ func TestNewAgentInstance_InvalidExecConfigDoesNotExit(t *testing.T) {
 		},
 	}
 
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{})
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{}, "")
 	if agent == nil {
 		t.Fatal("expected agent instance, got nil")
 	}
@@ -374,3 +374,31 @@ func TestNewAgentInstance_InvalidExecConfigDoesNotExit(t *testing.T) {
 		t.Fatal("read_file tool should still be registered")
 	}
 }
+func TestNewAgentInstance_IsolatedWorkspace(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace: tmpDir,
+				ModelName: "test-model",
+			},
+		},
+	}
+
+	isolationID := "user-123"
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{}, isolationID)
+
+	expectedWorkspace := filepath.Join(tmpDir, "sessions", isolationID, "workspace")
+	if agent.Workspace != expectedWorkspace {
+		t.Fatalf("Workspace = %q, want %q", agent.Workspace, expectedWorkspace)
+	}
+
+	// Verify the directory exists
+	info, err := os.Stat(agent.Workspace)
+	if err != nil {
+		t.Fatalf("os.Stat(agent.Workspace) failed: %v", err)
+	}
+	if !info.IsDir() {
+		t.Fatal("agent.Workspace is not a directory")
+	}
+}
diff --git a/pkg/agent/isolation_tools_test.go b/pkg/agent/isolation_tools_test.go
new file mode 100644
index 000000000..499cbf3c9
--- /dev/null
+++ b/pkg/agent/isolation_tools_test.go
@@ -0,0 +1,122 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+type isolationMockTool struct {
+	name string
+}
+
+func (m *isolationMockTool) Name() string        { return m.name }
+func (m *isolationMockTool) Description() string { return "mock tool" }
+func (m *isolationMockTool) Parameters() map[string]any {
+	return map[string]any{"type": "object", "properties": map[string]any{}}
+}
+func (m *isolationMockTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	return tools.SilentResult("executed")
+}
+
+func TestIsolationLacksManualTools(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "picoclaw-isolation-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{}
+	cfg.Agents.Defaults.Workspace = tmpDir
+	cfg.Agents.Defaults.ModelName = "test-model"
+
+	msgBus := bus.NewMessageBus()
+	provider := &isolationMockProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	tool := &isolationMockTool{name: "my_custom_tool"}
+	al.RegisterTool(tool)
+
+	// chatID "direct" does NOT use isolation
+	resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session1", "cli", "direct")
+	if err != nil {
+		t.Errorf("ProcessDirectWithChannel failed: %v", err)
+	}
+	if resp != "Found tool" {
+		t.Errorf("Direct response: %s, want Found tool", resp)
+	}
+
+	// chatID "chat1" DOES use isolation - transient agent instance is created
+	resp, err = al.ProcessDirectWithChannel(context.Background(), "hello", "session1", "cli", "chat1")
+	if err != nil {
+		t.Errorf("ProcessDirectWithChannel (isolated) failed: %v", err)
+	}
+	if resp != "Found tool" {
+		t.Errorf("Isolated response: %s, want Found tool (fixed)", resp)
+	}
+}
+
+func TestManualToolsPreservedAfterReload(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "picoclaw-reload-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{}
+	cfg.Agents.Defaults.Workspace = tmpDir
+	cfg.Agents.Defaults.ModelName = "test-model"
+
+	msgBus := bus.NewMessageBus()
+	provider := &isolationMockProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	tool := &isolationMockTool{name: "my_custom_tool"}
+	al.RegisterTool(tool)
+
+	// Reload with same config and provider - should preserve manual tools
+	err = al.ReloadProviderAndConfig(context.Background(), provider, cfg)
+	if err != nil {
+		t.Fatalf("Reload failed: %v", err)
+	}
+
+	// Check if tool is still visible to the new registry
+	resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session1", "cli", "direct")
+	if err != nil {
+		t.Errorf("ProcessDirectWithChannel failed: %v", err)
+	}
+	if resp != "Found tool" {
+		t.Errorf("Response after reload: %s, want Found tool", resp)
+	}
+}
+
+type isolationMockProvider struct{}
+
+func (m *isolationMockProvider) Chat(
+	ctx context.Context,
+	msgs []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	found := false
+	for _, t := range tools {
+		if t.Function.Name == "my_custom_tool" {
+			found = true
+			break
+		}
+	}
+	if found {
+		return &providers.LLMResponse{Content: "Found tool"}, nil
+	}
+	return &providers.LLMResponse{Content: "Tool NOT found"}, nil
+}
+
+func (m *isolationMockProvider) GetDefaultModel() string {
+	return "mock"
+}
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index 6cfbe1a56..864e5ecc2 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -59,11 +59,20 @@ type AgentLoop struct {
 	steering       *steeringQueue
 	pendingSkills  sync.Map
 	mu             sync.RWMutex
+	manualTools    []tools.Tool
 
 	// Concurrent turn management (from HEAD)
 	activeTurnStates sync.Map     // key: sessionKey (string), value: *turnState
 	subTurnCounter   atomic.Int64 // Counter for generating unique SubTurn IDs
 
+	// Agent instance caching for multi-user isolation
+	// Each unique chatID gets its own agent instance to maintain state/model selection
+	agentCache     sync.Map // key: channel:chatID, value: *AgentInstance
+	agentCacheMu   sync.RWMutex
+	agentCacheTTL  time.Duration // How long to keep cached agents alive
+	agentCleaner   *time.Ticker  // Periodic cleanup of stale cached agents
+	lastCacheCheck sync.Map      // key: channel:chatID, value: time.Time (last access time)
+
 	// Turn tracking (from Incoming)
 	turnSeq        atomic.Uint64
 	activeRequests sync.WaitGroup
@@ -103,7 +112,7 @@ const (
 	defaultResponse            = "The model returned an empty response. This may indicate a provider error or token limit."
 	toolLimitResponse          = "I've reached `max_tool_iterations` without a final response. Increase `max_tool_iterations` in config.json if this task needs more tool steps."
 	handledToolResponseSummary = "Requested output delivered via tool attachment."
-	sessionKeyAgentPrefix      = "agent:"
+	sessionKeyAgentPrefix      = "agent::"
 	metadataKeyAccountID       = "account_id"
 	metadataKeyGuildID         = "guild_id"
 	metadataKeyTeamID          = "team_id"
@@ -183,6 +192,13 @@ func registerSharedTools(
 			continue
 		}
 
+		// Re-register manual tools first so they can be overwritten by core shared tools if needed
+		al.mu.RLock()
+		for _, tool := range al.manualTools {
+			agent.Tools.Register(tool)
+		}
+		al.mu.RUnlock()
+
 		if cfg.Tools.IsToolEnabled("web") {
 			searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptions{
 				BraveAPIKeys:          cfg.Tools.Web.Brave.APIKeys.Values(),
@@ -730,7 +746,7 @@ func (al *AgentLoop) buildContinuationTarget(msg bus.InboundMessage) (*continuat
 	}
 
 	return &continuationTarget{
-		SessionKey: resolveScopeKey(route, msg.SessionKey),
+		SessionKey: resolveScopeKey(route, msg.SessionKey, msg.ChatID, route.AgentID),
 		Channel:    msg.Channel,
 		ChatID:     msg.ChatID,
 	}, nil
@@ -985,6 +1001,21 @@ func (al *AgentLoop) RegisterTool(tool tools.Tool) {
 			agent.Tools.Register(tool)
 		}
 	}
+
+	al.mu.Lock()
+	defer al.mu.Unlock()
+	// Check for duplicates by name and overwrite
+	found := false
+	for i, t := range al.manualTools {
+		if t.Name() == tool.Name() {
+			al.manualTools[i] = tool
+			found = true
+			break
+		}
+	}
+	if !found {
+		al.manualTools = append(al.manualTools, tool)
+	}
 }
 
 func (al *AgentLoop) SetChannelManager(cm *channels.Manager) {
@@ -1387,11 +1418,63 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 		return al.processSystemMessage(ctx, msg)
 	}
 
-	route, agent, routeErr := al.resolveMessageRoute(msg)
+	route, baseAgent, routeErr := al.resolveMessageRoute(msg)
 	if routeErr != nil {
 		return "", routeErr
 	}
 
+	agent := baseAgent
+	isolationID := msg.ChatID
+	if isolationID != "" && isolationID != "direct" {
+		// Check agent instance cache first (keyed by channel:chatID)
+		cacheKey := msg.Channel + ":" + isolationID
+		if cached, ok := al.agentCache.Load(cacheKey); ok {
+			agent = cached.(*AgentInstance)
+			// Update last access time for TTL tracking
+			al.lastCacheCheck.Store(cacheKey, time.Now())
+
+			logger.InfoCF("agent", "Reusing cached agent instance", map[string]any{
+				"agent_id":     agent.ID,
+				"cache_key":    cacheKey,
+				"isolation_id": isolationID,
+			})
+		} else {
+			// Create a transient isolated instance for this chat session
+			// This ensures workspace, memory, and sessions are private to the chat_id.
+
+			// Determine the original config for this agent to preserve its specialized prompt/skills
+			var ac *config.AgentConfig
+			for i := range al.cfg.Agents.List {
+				if routing.NormalizeAgentID(al.cfg.Agents.List[i].ID) == route.AgentID {
+					ac = &al.cfg.Agents.List[i]
+					break
+				}
+			}
+
+			// Create a new instance with the isolationID
+			// NewAgentInstance uses isolationID to sub-path the workspace
+			agent = NewAgentInstance(ac, &al.cfg.Agents.Defaults, al.cfg, baseAgent.Provider, isolationID)
+
+			// Set its ID to match the routed agent so prompts and logs match
+			agent.ID = route.AgentID
+
+			// Re-register shared tools (web, message, spawn) to this transient agent
+			// We pass a mini-registry containing only this agent
+			registerSharedTools(al, al.cfg, al.bus, &AgentRegistry{agents: map[string]*AgentInstance{agent.ID: agent}}, baseAgent.Provider)
+
+			// Cache this agent instance per chat session
+			al.agentCache.Store(cacheKey, agent)
+			al.lastCacheCheck.Store(cacheKey, time.Now())
+
+			logger.InfoCF("agent", "Created isolated transient agent", map[string]any{
+				"agent_id":     agent.ID,
+				"cache_key":    cacheKey,
+				"isolation_id": isolationID,
+				"workspace":    agent.Workspace,
+			})
+		}
+	}
+
 	// Reset message-tool state for this round so we don't skip publishing due to a previous round.
 	if tool, ok := agent.Tools.Get("message"); ok {
 		if resetter, ok := tool.(interface{ ResetSentInRound() }); ok {
@@ -1400,7 +1483,8 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 	}
 
 	// Resolve session key from route, while preserving explicit agent-scoped keys.
-	scopeKey := resolveScopeKey(route, msg.SessionKey)
+	// If caller provides a session key, respect it. Otherwise, derive from chatID for isolation.
+	scopeKey := resolveScopeKey(route, msg.SessionKey, msg.ChatID, agent.ID)
 	sessionKey := scopeKey
 
 	logger.InfoCF("agent", "Routed message",
@@ -1468,10 +1552,19 @@ func (al *AgentLoop) resolveMessageRoute(msg bus.InboundMessage) (routing.Resolv
 	return route, agent, nil
 }
 
-func resolveScopeKey(route routing.ResolvedRoute, msgSessionKey string) string {
+func resolveScopeKey(route routing.ResolvedRoute, msgSessionKey, chatID, agentID string) string {
+	// 1. If caller explicitly provides a session key with agent prefix, use it as-is
 	if msgSessionKey != "" && strings.HasPrefix(msgSessionKey, sessionKeyAgentPrefix) {
 		return msgSessionKey
 	}
+
+	// 2. If a unique chatID is provided, use it to create an isolated session per chat
+	// This ensures each Teams conversation (or any unique chat) has separate session history
+	if chatID != "" && chatID != "direct" {
+		return fmt.Sprintf("%s:%s:%s", sessionKeyAgentPrefix, agentID, chatID)
+	}
+
+	// 3. Fall back to route's default session key
 	return route.SessionKey
 }
 
@@ -1485,7 +1578,7 @@ func (al *AgentLoop) resolveSteeringTarget(msg bus.InboundMessage) (string, stri
 		return "", "", false
 	}
 
-	return resolveScopeKey(route, msg.SessionKey), agent.ID, true
+	return resolveScopeKey(route, msg.SessionKey, msg.ChatID, agent.ID), agent.ID, true
 }
 
 func (al *AgentLoop) requeueInboundMessage(msg bus.InboundMessage) error {
diff --git a/pkg/agent/loop_mcp.go b/pkg/agent/loop_mcp.go
index e35609340..39e3b4d60 100644
--- a/pkg/agent/loop_mcp.go
+++ b/pkg/agent/loop_mcp.go
@@ -64,7 +64,7 @@ func (al *AgentLoop) EnsureMCPInitialized(ctx context.Context) error {
 		return nil
 	}
 
-	if al.cfg.Tools.MCP.Servers == nil || len(al.cfg.Tools.MCP.Servers) == 0 {
+	if len(al.cfg.Tools.MCP.Servers) == 0 {
 		logger.WarnCF("agent", "MCP is enabled but no servers are configured, skipping MCP initialization", nil)
 		return nil
 	}
diff --git a/pkg/agent/loop_test.go b/pkg/agent/loop_test.go
index 9513d8aca..cc81f181c 100644
--- a/pkg/agent/loop_test.go
+++ b/pkg/agent/loop_test.go
@@ -670,7 +670,7 @@ func TestProcessMessage_MediaToolHandledSkipsFollowUpLLMAndFinalText(t *testing.
 	if err != nil {
 		t.Fatalf("resolveMessageRoute() error = %v", err)
 	}
-	sessionKey := resolveScopeKey(route, "")
+	sessionKey := resolveScopeKey(route, "", "chat1", route.AgentID)
 	history := defaultAgent.Sessions.GetHistory(sessionKey)
 	if len(history) == 0 {
 		t.Fatal("expected session history to be saved")
@@ -1399,11 +1399,8 @@ func TestProcessMessage_UsesRouteSessionKey(t *testing.T) {
 		},
 	}
 
-	route := al.registry.ResolveRoute(routing.RouteInput{
-		Channel: msg.Channel,
-		Peer:    extractPeer(msg),
-	})
-	sessionKey := route.SessionKey
+	// With chatID isolation, session key is derived from chatID
+	sessionKey := fmt.Sprintf("agent:::main:%s", msg.ChatID)
 
 	defaultAgent := al.registry.GetDefaultAgent()
 	if defaultAgent == nil {
@@ -2087,7 +2084,7 @@ func TestAgentLoop_ToolLimitUsesDedicatedFallback(t *testing.T) {
 	al := NewAgentLoop(cfg, msgBus, provider)
 	al.RegisterTool(&toolLimitTestTool{})
 
-	response, err := al.ProcessDirectWithChannel(context.Background(), "hello", "tool-limit", "test", "chat1")
+	response, err := al.ProcessDirectWithChannel(context.Background(), "hello", "tool-limit", "test", "direct")
 	if err != nil {
 		t.Fatalf("ProcessDirectWithChannel failed: %v", err)
 	}
diff --git a/pkg/agent/registry.go b/pkg/agent/registry.go
index 58b7ce440..ca585d533 100644
--- a/pkg/agent/registry.go
+++ b/pkg/agent/registry.go
@@ -33,14 +33,15 @@ func NewAgentRegistry(
 			ID:      "main",
 			Default: true,
 		}
-		instance := NewAgentInstance(implicitAgent, &cfg.Agents.Defaults, cfg, provider)
+		instance := NewAgentInstance(implicitAgent, &cfg.Agents.Defaults, cfg, provider, "")
 		registry.agents["main"] = instance
 		logger.InfoCF("agent", "Created implicit main agent (no agents.list configured)", nil)
 	} else {
 		for i := range agentConfigs {
 			ac := &agentConfigs[i]
 			id := routing.NormalizeAgentID(ac.ID)
-			instance := NewAgentInstance(ac, &cfg.Agents.Defaults, cfg, provider)
+			instance := NewAgentInstance(ac, &cfg.Agents.Defaults, cfg, provider, "")
+
 			registry.agents[id] = instance
 			logger.InfoCF("agent", "Registered agent",
 				map[string]any{
diff --git a/pkg/agent/steering_test.go b/pkg/agent/steering_test.go
index 75ba9861d..982d61b16 100644
--- a/pkg/agent/steering_test.go
+++ b/pkg/agent/steering_test.go
@@ -298,7 +298,7 @@ func TestAgentLoop_Continue_NoMessages(t *testing.T) {
 		t.Fatal("expected provider to be initialized")
 	}
 
-	resp, err := al.Continue(context.Background(), "test-session", "test", "chat1")
+	resp, err := al.Continue(context.Background(), "test-session", "test", "direct")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -331,7 +331,7 @@ func TestAgentLoop_Continue_WithMessages(t *testing.T) {
 
 	al.Steer(providers.Message{Role: "user", Content: "new direction"})
 
-	resp, err := al.Continue(context.Background(), "test-session", "test", "chat1")
+	resp, err := al.Continue(context.Background(), "test-session", "test", "direct")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -367,7 +367,7 @@ func TestDrainBusToSteering_RequeuesDifferentScopeMessage(t *testing.T) {
 	activeMsg := bus.InboundMessage{
 		Channel:  "telegram",
 		SenderID: "user1",
-		ChatID:   "chat1",
+		ChatID:   "direct",
 		Content:  "active turn",
 		Peer: bus.Peer{
 			Kind: "direct",
@@ -701,7 +701,7 @@ func TestAgentLoop_Steering_SkipsRemainingTools(t *testing.T) {
 			"do something",
 			"test-session",
 			"test",
-			"chat1",
+			"direct",
 		)
 		resultCh <- result{resp, err}
 	}()
@@ -783,7 +783,7 @@ func TestAgentLoop_Steering_InitialPoll(t *testing.T) {
 		"initial message",
 		"test-session",
 		"test",
-		"chat1",
+		"direct",
 	)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -843,7 +843,7 @@ func TestAgentLoop_Run_AutoContinuesLateSteeringMessage(t *testing.T) {
 	first := bus.InboundMessage{
 		Channel:  "test",
 		SenderID: "user1",
-		ChatID:   "chat1",
+		ChatID:   "direct",
 		Content:  "first message",
 		Peer: bus.Peer{
 			Kind: "direct",
@@ -853,7 +853,7 @@ func TestAgentLoop_Run_AutoContinuesLateSteeringMessage(t *testing.T) {
 	late := bus.InboundMessage{
 		Channel:  "test",
 		SenderID: "user1",
-		ChatID:   "chat1",
+		ChatID:   "direct",
 		Content:  "late append",
 		Peer: bus.Peer{
 			Kind: "direct",
@@ -970,7 +970,7 @@ func TestAgentLoop_Steering_DirectResponseContinuesWithQueuedMessage(t *testing.
 			"initial request",
 			sessionKey,
 			"test",
-			"chat1",
+			"direct",
 		)
 		resultCh <- struct {
 			resp string
@@ -1073,7 +1073,7 @@ func TestAgentLoop_Continue_PreservesSteeringMedia(t *testing.T) {
 		t.Fatalf("Steer failed: %v", err)
 	}
 
-	resp, err := al.Continue(context.Background(), sessionKey, "test", "chat1")
+	resp, err := al.Continue(context.Background(), sessionKey, "test", "direct")
 	if err != nil {
 		t.Fatalf("Continue failed: %v", err)
 	}
@@ -1184,7 +1184,7 @@ func TestAgentLoop_InterruptGraceful_UsesTerminalNoToolCall(t *testing.T) {
 			"do something",
 			sessionKey,
 			"test",
-			"chat1",
+			"direct",
 		)
 		resultCh <- result{resp: resp, err: err}
 	}()
@@ -1202,7 +1202,7 @@ func TestAgentLoop_InterruptGraceful_UsesTerminalNoToolCall(t *testing.T) {
 	if active.SessionKey != sessionKey {
 		t.Fatalf("expected active session %q, got %q", sessionKey, active.SessionKey)
 	}
-	if active.Channel != "test" || active.ChatID != "chat1" {
+	if active.Channel != "test" || active.ChatID != "direct" {
 		t.Fatalf("unexpected active turn target: %#v", active)
 	}
 
@@ -1349,7 +1349,7 @@ func TestAgentLoop_InterruptHard_RestoresSession(t *testing.T) {
 			"do work",
 			sessionKey,
 			"test",
-			"chat1",
+			"direct",
 		)
 		resultCh <- result{resp: resp, err: err}
 	}()
@@ -1518,7 +1518,7 @@ func TestAgentLoop_Steering_SkippedToolsHaveErrorResults(t *testing.T) {
 	resultCh := make(chan string, 1)
 	go func() {
 		resp, _ := al.ProcessDirectWithChannel(
-			context.Background(), "go", "test-session", "test", "chat1",
+			context.Background(), "go", "test-session", "test", "direct",
 		)
 		resultCh <- resp
 	}()
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
index bf1d90e70..631238cb6 100644
--- a/pkg/gateway/gateway.go
+++ b/pkg/gateway/gateway.go
@@ -208,11 +208,14 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 
 	// Setup synchronous /chat endpoint handler
 	if cfg.Gateway.ChatEnabled {
-		runningServices.HealthServer.SetChatFunc(func(ctx context.Context, message, sessionID string) (string, error) {
+		runningServices.HealthServer.SetChatFunc(func(ctx context.Context, message, sessionID, chatID string) (string, error) {
 			if sessionID == "" {
 				sessionID = "http-chat"
 			}
-			return agentLoop.ProcessDirectWithChannel(ctx, message, sessionID, "http", "chat")
+			if chatID == "" {
+				chatID = "chat"
+			}
+			return agentLoop.ProcessDirectWithChannel(ctx, message, sessionID, "http", chatID)
 		})
 	}
 
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 4eea0118f..2ff2dae6e 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -17,6 +17,7 @@ import (
 type ChatRequest struct {
 	Message   string `json:"message"`
 	SessionID string `json:"session_id,omitempty"`
+	ChatID    string `json:"chat_id,omitempty"` // Alias for session_id to match PicoClaw terminology
 }
 
 // ChatResponse is the JSON response from /chat.
@@ -43,7 +44,7 @@ type Server struct {
 	startTime     time.Time
 	reloadFunc    func() error
 	authToken     string // optional bearer token for protected endpoints
-	chatFunc      func(ctx context.Context, message, sessionID string) (string, error)
+	chatFunc      func(ctx context.Context, message, sessionID, chatID string) (string, error)
 	apiKey        string
 	chatResults   map[string]*chatStatus
 	chatResultsMu sync.RWMutex
@@ -157,7 +158,7 @@ func (s *Server) SetReloadFunc(fn func() error) {
 // fn receives the user message and an optional session ID and must return the
 // agent's reply (or an error). It is called synchronously inside the HTTP
 // handler, so the write timeout on the server governs the maximum duration.
-func (s *Server) SetChatFunc(fn func(ctx context.Context, message, sessionID string) (string, error)) {
+func (s *Server) SetChatFunc(fn func(ctx context.Context, message, sessionID, chatID string) (string, error)) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	s.chatFunc = fn
@@ -335,6 +336,56 @@ func (s *Server) handlePostChat(w http.ResponseWriter, r *http.Request) {
 	}
 
 	sessionID := req.SessionID
+	if sessionID == "" && req.ChatID != "" {
+		sessionID = req.ChatID
+	}
+
+	chatID := req.ChatID
+	if chatID == "" {
+		// Try to extract ChatID/TenantID from common headers
+		// These are ordered by specificity/reliability
+		headers := []string{
+			"X-PicoClaw-Chat-ID",
+			"X-User-ID",
+			"X-Session-ID",
+			"X-MS-CLIENT-PRINCIPAL-ID",   // Azure App Service / Container Apps (EasyAuth)
+			"X-MS-CLIENT-PRINCIPAL-NAME", // Azure App Service Email/Username
+			"Ocp-Apim-Subscription-Id",   // Azure APIM (if configured)
+		}
+
+		for _, h := range headers {
+			if val := r.Header.Get(h); val != "" {
+				chatID = val
+				break
+			}
+		}
+
+		// Fallback to SessionID if provided in body, otherwise empty (global)
+		if chatID == "" {
+			chatID = req.SessionID
+		}
+	}
+
+	if chatID != "" {
+		logger.InfoCF("api", "Resolved isolation ID for request", map[string]any{
+			"chat_id":    chatID,
+			"session_id": sessionID,
+		})
+	} else {
+		// Log all headers for debugging (excluding sensitive ones)
+		headers := make(map[string]string)
+		for k, v := range r.Header {
+			if k == "Authorization" || k == "X-Api-Key" || k == "Ocp-Apim-Subscription-Key" {
+				headers[k] = "REDACTED"
+			} else if len(v) > 0 {
+				headers[k] = v[0]
+			}
+		}
+		logger.DebugCF("api", "Chat request received without explicit ChatID. Checking headers...", map[string]any{
+			"headers": headers,
+		})
+	}
+
 	if sessionID == "" {
 		sessionID = fmt.Sprintf("chat-%d", time.Now().UnixNano())
 	}
@@ -352,7 +403,7 @@ func (s *Server) handlePostChat(w http.ResponseWriter, r *http.Request) {
 		// which will be cancelled when this request finishes.
 		ctx := context.Background()
 		logger.Debugf("Starting async chat for session %s", sessionID)
-		reply, err := chatFunc(ctx, req.Message, sessionID)
+		reply, err := chatFunc(ctx, req.Message, sessionID, chatID)
 
 		s.chatResultsMu.Lock()
 		defer s.chatResultsMu.Unlock()
diff --git a/pkg/skills/loader.go b/pkg/skills/loader.go
index bdabd63b8..03e94e3b8 100644
--- a/pkg/skills/loader.go
+++ b/pkg/skills/loader.go
@@ -59,18 +59,19 @@ func (info SkillInfo) validate() error {
 }
 
 type SkillsLoader struct {
-	workspace        string
-	workspaceSkills  string // workspace skills (project-level)
-	globalSkills     string // global skills (~/.picoclaw/skills)
-	builtinSkills    string // builtin skills
-	whitelist        []string
-	whitelistEnabled bool
+	workspace           string
+	workspaceSkills     string // workspace skills (project-level)
+	baseWorkspaceSkills string // fallback workspace skills (if isolated)
+	globalSkills        string // global skills (~/.picoclaw/skills)
+	builtinSkills       string // builtin skills
+	whitelist           []string
+	whitelistEnabled    bool
 }
 
 // SkillRoots returns all unique skill root directories used by this loader.
 // The order follows resolution priority: workspace > global > builtin.
 func (sl *SkillsLoader) SkillRoots() []string {
-	roots := []string{sl.workspaceSkills, sl.globalSkills, sl.builtinSkills}
+	roots := []string{sl.workspaceSkills, sl.baseWorkspaceSkills, sl.globalSkills, sl.builtinSkills}
 	seen := make(map[string]struct{}, len(roots))
 	out := make([]string, 0, len(roots))
 
@@ -92,18 +93,20 @@ func (sl *SkillsLoader) SkillRoots() []string {
 
 func NewSkillsLoader(
 	workspace string,
+	baseWorkspace string,
 	globalSkills string,
 	builtinSkills string,
 	whitelist []string,
 	whitelistEnabled bool,
 ) *SkillsLoader {
 	return &SkillsLoader{
-		workspace:        workspace,
-		workspaceSkills:  filepath.Join(workspace, "skills"),
-		globalSkills:     globalSkills, // ~/.picoclaw/skills
-		builtinSkills:    builtinSkills,
-		whitelist:        whitelist,
-		whitelistEnabled: whitelistEnabled,
+		workspace:           workspace,
+		workspaceSkills:     filepath.Join(workspace, "skills"),
+		baseWorkspaceSkills: filepath.Join(baseWorkspace, "skills"),
+		globalSkills:        globalSkills, // ~/.picoclaw/skills
+		builtinSkills:       builtinSkills,
+		whitelist:           whitelist,
+		whitelistEnabled:    whitelistEnabled,
 	}
 }
 
@@ -173,8 +176,9 @@ func (sl *SkillsLoader) ListSkills() []SkillInfo {
 		}
 	}
 
-	// Priority: workspace > global > builtin
+	// Priority: workspace > base workspace > global > builtin
 	addSkills(sl.workspaceSkills, "workspace")
+	addSkills(sl.baseWorkspaceSkills, "shared")
 	addSkills(sl.globalSkills, "global")
 	addSkills(sl.builtinSkills, "builtin")
 
@@ -204,6 +208,14 @@ func (sl *SkillsLoader) LoadSkill(name string) (string, bool) {
 	}
 	// ...
 
+	// 1b. load from base workspace skills (fallback if isolated)
+	if sl.baseWorkspaceSkills != "" && sl.baseWorkspaceSkills != sl.workspaceSkills {
+		skillFile := filepath.Join(sl.baseWorkspaceSkills, name, "SKILL.md")
+		if content, err := os.ReadFile(skillFile); err == nil {
+			return sl.stripFrontmatter(string(content)), true
+		}
+	}
+
 	// 2. then load from global skills (~/.picoclaw/skills)
 	if sl.globalSkills != "" {
 		skillFile := filepath.Join(sl.globalSkills, name, "SKILL.md")
diff --git a/pkg/skills/loader_test.go b/pkg/skills/loader_test.go
index 4d0610160..5373f3470 100644
--- a/pkg/skills/loader_test.go
+++ b/pkg/skills/loader_test.go
@@ -155,7 +155,7 @@ func TestListSkillsWorkspaceOverridesGlobal(t *testing.T) {
 	createSkillDir(t, filepath.Join(ws, "skills"), "my-skill", "my-skill", "workspace version")
 	createSkillDir(t, global, "my-skill", "my-skill", "global version")
 
-	sl := NewSkillsLoader(ws, global, "", nil, false)
+	sl := NewSkillsLoader(ws, ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -172,7 +172,7 @@ func TestListSkillsGlobalOverridesBuiltin(t *testing.T) {
 	createSkillDir(t, global, "my-skill", "my-skill", "global version")
 	createSkillDir(t, builtin, "my-skill", "my-skill", "builtin version")
 
-	sl := NewSkillsLoader(ws, global, builtin, nil, false)
+	sl := NewSkillsLoader(ws, ws, global, builtin, nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -189,7 +189,7 @@ func TestListSkillsMetadataNameDedup(t *testing.T) {
 	createSkillDir(t, filepath.Join(ws, "skills"), "dir-a", "shared-name", "workspace version")
 	createSkillDir(t, global, "dir-b", "shared-name", "global version")
 
-	sl := NewSkillsLoader(ws, global, "", nil, false)
+	sl := NewSkillsLoader(ws, ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -207,7 +207,7 @@ func TestListSkillsMultipleDistinctSkills(t *testing.T) {
 	createSkillDir(t, global, "skill-b", "skill-b", "desc b")
 	createSkillDir(t, builtin, "skill-c", "skill-c", "desc c")
 
-	sl := NewSkillsLoader(ws, global, builtin, nil, false)
+	sl := NewSkillsLoader(ws, ws, global, builtin, nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 3)
@@ -230,7 +230,7 @@ func TestListSkillsInvalidSkillSkipped(t *testing.T) {
 	// Valid skill
 	createSkillDir(t, global, "good-skill", "good-skill", "desc")
 
-	sl := NewSkillsLoader(ws, global, "", nil, false)
+	sl := NewSkillsLoader(ws, ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -243,7 +243,7 @@ func TestListSkillsEmptyAndNonexistentDirs(t *testing.T) {
 	emptyDir := filepath.Join(tmp, "empty")
 	require.NoError(t, os.MkdirAll(emptyDir, 0o755))
 
-	sl := NewSkillsLoader(ws, emptyDir, filepath.Join(tmp, "nonexistent"), nil, false)
+	sl := NewSkillsLoader(ws, ws, emptyDir, filepath.Join(tmp, "nonexistent"), nil, false)
 	skills := sl.ListSkills()
 
 	assert.Empty(t, skills)
@@ -259,7 +259,7 @@ func TestListSkillsDirWithoutSkillMD(t *testing.T) {
 	// Valid skill alongside
 	createSkillDir(t, global, "real-skill", "real-skill", "desc")
 
-	sl := NewSkillsLoader(ws, global, "", nil, false)
+	sl := NewSkillsLoader(ws, ws, global, "", nil, false)
 	skills := sl.ListSkills()
 
 	assert.Len(t, skills, 1)
@@ -333,7 +333,7 @@ func TestSkillRootsTrimsWhitespaceAndDedups(t *testing.T) {
 	global := filepath.Join(tmp, "global")
 	builtin := filepath.Join(tmp, "builtin")
 
-	sl := NewSkillsLoader(workspace, "  "+global+"  ", "\t"+builtin+"\n", nil, false)
+	sl := NewSkillsLoader(workspace, workspace, "  "+global+"  ", "\t"+builtin+"\n", nil, false)
 	roots := sl.SkillRoots()
 
 	assert.Equal(t, []string{
@@ -429,14 +429,14 @@ func TestListSkillsWithWhitelist(t *testing.T) {
 	createSkillDir(t, builtin, "skill-c", "skill-c", "desc c")
 
 	t.Run("allow-one", func(t *testing.T) {
-		sl := NewSkillsLoader(ws, global, builtin, []string{"skill-a"}, true)
+		sl := NewSkillsLoader(ws, ws, global, builtin, []string{"skill-a"}, true)
 		skills := sl.ListSkills()
 		assert.Len(t, skills, 1)
 		assert.Equal(t, "skill-a", skills[0].Name)
 	})
 
 	t.Run("allow-two", func(t *testing.T) {
-		sl := NewSkillsLoader(ws, global, builtin, []string{"skill-a", "skill-c"}, true)
+		sl := NewSkillsLoader(ws, ws, global, builtin, []string{"skill-a", "skill-c"}, true)
 		skills := sl.ListSkills()
 		assert.Len(t, skills, 2)
 		names := []string{skills[0].Name, skills[1].Name}
@@ -445,19 +445,19 @@ func TestListSkillsWithWhitelist(t *testing.T) {
 	})
 
 	t.Run("allow-none", func(t *testing.T) {
-		sl := NewSkillsLoader(ws, global, builtin, []string{"non-existent"}, true)
+		sl := NewSkillsLoader(ws, ws, global, builtin, []string{"non-existent"}, true)
 		skills := sl.ListSkills()
 		assert.Empty(t, skills)
 	})
 
 	t.Run("empty-whitelist-allows-all", func(t *testing.T) {
-		sl := NewSkillsLoader(ws, global, builtin, []string{}, false)
+		sl := NewSkillsLoader(ws, ws, global, builtin, []string{}, false)
 		skills := sl.ListSkills()
 		assert.Len(t, skills, 3)
 	})
 
 	t.Run("nil-whitelist-allows-all", func(t *testing.T) {
-		sl := NewSkillsLoader(ws, global, builtin, nil, false)
+		sl := NewSkillsLoader(ws, ws, global, builtin, nil, false)
 		skills := sl.ListSkills()
 		assert.Len(t, skills, 3)
 	})
diff --git a/web/backend/api/skills.go b/web/backend/api/skills.go
index 56cb155b7..608672172 100644
--- a/web/backend/api/skills.go
+++ b/web/backend/api/skills.go
@@ -504,6 +504,7 @@ func (h *Handler) handleDeleteSkill(w http.ResponseWriter, r *http.Request) {
 
 func newSkillsLoader(workspace string) *skills.SkillsLoader {
 	return skills.NewSkillsLoader(
+		workspace,
 		workspace,
 		filepath.Join(globalConfigDir(), "skills"),
 		builtinSkillsDir(),

From 7dee43b0dc040022ec046c29dc663767903d2150 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Thu, 26 Mar 2026 20:00:11 +0100
Subject: [PATCH 09/25] test: merge filesystem isolation validation into
 isolation_tools_test.go

---
 pkg/agent/isolation_tools_test.go | 109 ++++++++++++++++++++++++++++++
 pkg/agent/secret.txt              |   1 +
 2 files changed, 110 insertions(+)
 create mode 100644 pkg/agent/secret.txt

diff --git a/pkg/agent/isolation_tools_test.go b/pkg/agent/isolation_tools_test.go
index 499cbf3c9..21bd810a5 100644
--- a/pkg/agent/isolation_tools_test.go
+++ b/pkg/agent/isolation_tools_test.go
@@ -2,7 +2,9 @@ package agent
 
 import (
 	"context"
+	"fmt"
 	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
@@ -95,6 +97,113 @@ func TestManualToolsPreservedAfterReload(t *testing.T) {
 	}
 }
 
+type tenantIsolationMockProvider struct {
+	toolCalls []providers.ToolCall
+	response  string
+}
+
+func (p *tenantIsolationMockProvider) Chat(
+	ctx context.Context, msgs []providers.Message, tools []providers.ToolDefinition,
+	model string, opts map[string]any,
+) (*providers.LLMResponse, error) {
+	if len(p.toolCalls) > 0 {
+		res := &providers.LLMResponse{
+			ToolCalls: p.toolCalls,
+		}
+		p.toolCalls = nil // Clear so it doesn't loop
+		return res, nil
+	}
+	return &providers.LLMResponse{Content: p.response}, nil
+}
+
+func (p *tenantIsolationMockProvider) GetDefaultModel() string { return "test-model" }
+
+func TestProcessMessage_IsolatedTenant_UsesPrivateWorkspace(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-isolation-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:           tmpDir,
+				ModelName:           "test-model",
+				MaxTokens:           4096,
+				MaxToolIterations:   10,
+				RestrictToWorkspace: true,
+			},
+		},
+	}
+	cfg.Tools.WriteFile.Enabled = true
+
+	msgBus := bus.NewMessageBus()
+	provider := &tenantIsolationMockProvider{
+		toolCalls: []providers.ToolCall{
+			{
+				ID:   "call1",
+				Type: "function",
+				Name: "write_file",
+				Arguments: map[string]any{
+					"path":    "secret.txt",
+					"content": "isolated-content",
+				},
+			},
+		},
+		response: "File written.",
+	}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	defer al.Close()
+
+	isolationID := "tenant-A"
+	msg := bus.InboundMessage{
+		Channel:  "test-channel",
+		SenderID: "user1",
+		ChatID:   isolationID,
+		Content:  "Write the secret file",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	}
+
+	resp, err := al.processMessage(context.Background(), msg)
+	if err != nil {
+		t.Fatalf("processMessage failed: %v", err)
+	}
+	fmt.Printf("Agent Response: %s\n", resp)
+
+	// Verify the file was written to the ISOLATED workspace, NOT the global one
+	isolatedPath := filepath.Join(tmpDir, "sessions", isolationID, "workspace", "secret.txt")
+	globalPath := filepath.Join(tmpDir, "secret.txt")
+
+	// Debug: Print all files in tmpDir
+	t.Logf("Listing all files in %s:", tmpDir)
+	filepath.Walk(tmpDir, func(path string, info os.FileInfo, err error) error {
+		if !info.IsDir() {
+			t.Logf("Found file: %s", path)
+		}
+		return nil
+	})
+
+	if _, err := os.Stat(isolatedPath); os.IsNotExist(err) {
+		t.Errorf("expected file at %s to exist", isolatedPath)
+	}
+	if _, err := os.Stat(globalPath); err == nil {
+		t.Errorf("expected file at %s to NOT exist (leaked to global workspace)", globalPath)
+	}
+
+	// Verify history is in the base sessions directory with the isolated key
+	// agent:::main:tenant-A becomes agent___main_tenant-A
+	isoSessionPath := filepath.Join(tmpDir, "sessions", "agent___main_tenant-A.jsonl")
+	if _, err := os.Stat(isoSessionPath); os.IsNotExist(err) {
+		t.Errorf("expected history at %s to exist", isoSessionPath)
+	} else {
+		t.Logf("History exists at: %s", isoSessionPath)
+	}
+}
+
 type isolationMockProvider struct{}
 
 func (m *isolationMockProvider) Chat(
diff --git a/pkg/agent/secret.txt b/pkg/agent/secret.txt
new file mode 100644
index 000000000..d1af05448
--- /dev/null
+++ b/pkg/agent/secret.txt
@@ -0,0 +1 @@
+isolated-content
\ No newline at end of file

From 2a153bff02a55871faa1dae107d400fdbeb6f64c Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Thu, 26 Mar 2026 20:17:20 +0100
Subject: [PATCH 10/25] Synchronize hardening: added onboard purge,
 non-interactive mode, and diagnostic startup logs

---
 TEAMS_ID_MAPPING_ANALYSIS.md             | 363 +++++++++++++++++++++++
 TEAMS_QUICK_REFERENCE.md                 | 315 ++++++++++++++++++++
 cmd/picoclaw/internal/onboard/command.go |   7 +-
 cmd/picoclaw/internal/onboard/helpers.go |  34 ++-
 cmd/picoclaw/internal/onboard/purge.go   |  58 ++++
 pkg/gateway/gateway.go                   |   9 +
 6 files changed, 770 insertions(+), 16 deletions(-)
 create mode 100644 TEAMS_ID_MAPPING_ANALYSIS.md
 create mode 100644 TEAMS_QUICK_REFERENCE.md
 create mode 100644 cmd/picoclaw/internal/onboard/purge.go

diff --git a/TEAMS_ID_MAPPING_ANALYSIS.md b/TEAMS_ID_MAPPING_ANALYSIS.md
new file mode 100644
index 000000000..f26b14fed
--- /dev/null
+++ b/TEAMS_ID_MAPPING_ANALYSIS.md
@@ -0,0 +1,363 @@
+# Teams Channel Integration & ID Mapping Analysis
+
+## Executive Summary
+
+**Teams Channel Implementation Status**: ❌ **NOT YET IMPLEMENTED**
+- Search results show no Teams/MSTeams channel in `pkg/channels/`
+- Only reference found: migration config reference in `pkg/migrate/sources/openclaw/openclaw_config.go:123`
+- **Foundry Integration**: Only implemented as an LLM **provider** (Azure AI Foundry), not as a channel
+
+---
+
+## InboundMessage Structure (Bus Layer)
+
+**Location**: [pkg/bus/types.go](pkg/bus/types.go)
+
+### Core Fields Available
+
+```go
+type InboundMessage struct {
+	Channel    string            // Channel name (e.g., "teams", "slack", "telegram")
+	SenderID   string            // Platform-specific sender identifier
+	Sender     SenderInfo        // Structured sender information
+	ChatID     string            // Conversation/chat identifier (CRITICAL FOR ISOLATION)
+	Content    string            // Message text content
+	Media      []string          // Media references (attachments)
+	Peer       Peer              // Routing peer information
+	MessageID  string            // Platform-specific message ID
+	MediaScope string            // Media lifecycle tracking scope
+	SessionKey string            // Session key (optional, can be auto-resolved)
+	Metadata   map[string]string // Platform-specific metadata
+}
+```
+
+### SenderInfo Sub-structure
+
+```go
+type SenderInfo struct {
+	Platform    string // "telegram", "discord", "slack", "teams", etc.
+	PlatformID  string // Raw platform ID (e.g., Teams UserID "29:...")
+	CanonicalID string // Normalized "platform:id" format (e.g., "teams:29:...")
+	Username    string // Display username (e.g., "@alice")
+	DisplayName string // Full display name
+}
+```
+
+### Peer Sub-structure
+
+```go
+type Peer struct {
+	Kind string // "direct" | "group" | "channel" | ""
+	ID   string // Peer identifier (user_id, group_id, channel_id, etc.)
+}
+```
+
+---
+
+## ID Mapping for Hypothetical Teams Implementation
+
+### What Teams Would Need to Provide
+
+If Teams were to be integrated, the following IDs should map as follows:
+
+| Teams ID | InboundMessage Field | Notes |
+|----------|----------------------|-------|
+| User ID (e.g., `29:1ABC123`) | `SenderID`, `Sender.PlatformID` | Teams uses format `29:uuid` |
+| Conversation ID | `ChatID` | CRITICAL: Identifies conversation scope |
+| Team ID | `Metadata["team_id"]`, potentially routing input | Can be used for team-level routing |
+| Channel ID | `Peer.ID` (if channel) | When in Team channel |
+| Service URL | `Metadata["service_url"]` | Teams service endpoint |
+| Activity ID | `MessageID` | Platform message identifier |
+
+### Canonical ID Format
+
+**Pattern**: `platform:platform_id`
+
+**Example for Teams**: 
+```
+"teams:29:1ABC123" = Canonical ID for Teams user 29:1ABC123
+```
+
+Built via: [pkg/identity/identity.go](pkg/identity/identity.go)
+```go
+func BuildCanonicalID(platform, platformID string) string {
+	p := strings.ToLower(strings.TrimSpace(platform))
+	id := strings.TrimSpace(platformID)
+	if p == "" || id == "" {
+		return ""
+	}
+	return p + ":" + id  // "teams:29:abc123"
+}
+```
+
+---
+
+## ChatID Usage & Session Isolation
+
+**Location**: [pkg/agent/loop.go](pkg/agent/loop.go#L1250-L1270)
+
+### Current ChatID Role
+
+The `ChatID` field is **THE PRIMARY KEY** for conversation isolation:
+
+1. **Session Binding**: Each unique `ChatID` can map to a separate session depending on DMScope
+2. **Workspace Isolation**: When non-empty and not "direct", creates isolated agent workspace:
+   ```go
+   if isolationID != "" && isolationID != "direct" {
+       // Create transient isolated instance for this chat session
+       agent = NewAgentInstance(ac, cfg, baseAgent.Provider, isolationID)
+   }
+   ```
+3. **State Persistence**: Last ChatID tracked for workspace continuity
+
+**Example mapping**:
+- Single direct message with user → `ChatID = "teams:29:1ABC123"`
+- Team channel conversation → `ChatID = "teams-channel:xyz789"`
+- Group chat → `ChatID = "teams-groupchat:123abc"`
+
+---
+
+## Session Key Construction & Resolution
+
+**Location**: [pkg/routing/session_key.go](pkg/routing/session_key.go) + [pkg/routing/route.go](pkg/routing/route.go)
+
+### RouteInput (What Channel Provides to Router)
+
+```go
+type RouteInput struct {
+	Channel    string      // "teams" (if implemented)
+	AccountID  string      // Bot account/app ID
+	Peer       *RoutePeer  // Who message is from (user)
+	ParentPeer *RoutePeer  // Parent context (e.g., Team)
+	GuildID    string      // Guild/workspace ID (if applicable)
+	TeamID     string      // Teams Team ID (would go here)
+}
+```
+
+### ResolvedRoute Output
+
+```go
+type ResolvedRoute struct {
+	AgentID        string // Which agent handles this message
+	SessionKey     string // Session identifier pattern
+	MainSessionKey string // Main session fallback
+	MatchedBy      string // How routing was matched
+}
+```
+
+### Session Key Patterns
+
+**DMScope** configuration determines how sessions are keyed:
+
+| DMScope Mode | Format | Example | Use Case |
+|--------------|--------|---------|----------|
+| `DMScopeMain` | `agent:agentid:main` | `agent:teams-bot:main` | Single shared session |
+| `DMScopePerPeer` | `agent:agentid:direct:peerid` | `agent:teams-bot:direct:user123` | Per-user sessions |
+| `DMScopePerChannelPeer` | `agent:agentid:channel:direct:peerid` | `agent:teams-bot:teams:direct:user123` | Per-channel-per-user |
+| `DMScopePerAccountChannelPeer` | `agent:agentid:channel:account:direct:peerid` | `agent:teams-bot:teams:acct1:direct:user123` | Per-account-channel-user |
+
+**Location**: [pkg/routing/session_key.go:40-100](pkg/routing/session_key.go#L40-L100)
+
+```go
+// For Teams direct message:
+BuildAgentPeerSessionKey(SessionKeyParams{
+	AgentID:   "teams-bot",
+	Channel:   "teams",
+	AccountID: "bot-app-id",
+	Peer:      &RoutePeer{Kind: "direct", ID: "29:abc123"},
+	DMScope:   DMScopePerChannelPeer,
+})
+// Returns: "agent:teams-bot:teams:direct:29:abc123"
+```
+
+---
+
+## ID Priority Cascade for Agent Routing
+
+**Location**: [pkg/routing/route.go:68-126](pkg/routing/route.go#L68-L126)
+
+The agent resolver uses this **7-level priority**:
+
+1. **Peer binding** → Match on specific user/peer ID
+2. **Parent peer binding** → Match on parent context (Team, Guild, etc.)
+3. **Guild binding** → Match on Guild/Workspace ID
+4. **Team binding** → Match on Team ID ← **TEAMS WOULD USE THIS**
+5. **Account binding** → Match on account/app ID
+6. **Channel wildcard** → Match on channel with wildcard
+7. **Default agent** → Fallback
+
+**For Teams, routing would likely use**:
+- Level 2: ParentPeer = Team
+- Level 3: GuildID = Team ID  
+- Level 4: TeamID = Team ID
+
+---
+
+## Foundry Integration Status
+
+**Locations**: 
+- [pkg/providers/factory_provider.go:196](pkg/providers/factory_provider.go#L196)
+- [pkg/providers/openai_compat/provider.go:432](pkg/providers/openai_compat/provider.go#L432)
+
+### Current Foundry Support
+
+**Type**: LLM **Provider Only** (NOT Channel)
+
+```go
+case "azure-ai", "azure-foundry":
+    // Azure AI Foundry / Studio compatible with OpenAI API format
+    // Used for LLM backend, not message channeling
+```
+
+**What's Missing for Teams/Foundry Integration**:
+- ❌ No Teams Channel handler
+- ❌ No Foundry Agent channel integration
+- ❌ No Teams webhook receiver
+- ❌ No Teams message routing
+
+**What Exists**:
+- ✅ Azure AI Foundry as LLM provider backend
+- ✅ OpenAI-compatible API handling
+- ✅ Generic inbound message bus infrastructure
+
+---
+
+## Metadata Field Usage
+
+All channels populate `InboundMessage.Metadata` with platform-specific data:
+
+### Example: WeCom (for comparison)
+**Location**: [pkg/channels/wecom/app.go:605-620](pkg/channels/wecom/app.go#L605-L620)
+
+```go
+metadata := map[string]string{
+	"msg_type":    msg.MsgType,
+	"msg_id":      fmt.Sprintf("%d", msg.MsgId),
+	"agent_id":    fmt.Sprintf("%d", msg.AgentID),
+	"platform":    "wecom",
+	"media_id":    msg.MediaId,
+	"create_time": fmt.Sprintf("%d", msg.CreateTime),
+}
+```
+
+### For Teams Implementation, Would Include:
+
+```go
+metadata := map[string]string{
+	"team_id":        msg.TeamsTeamID,
+	"channel_id":     msg.TeamsChannelID,
+	"service_url":    msg.ServiceURL,
+	"activity_id":    msg.ActivityID,
+	"conversation_id": msg.ConversationID,
+	"from_user_id":   msg.FromUserID,
+	"platform":       "teams",
+	...
+}
+```
+
+---
+
+## Identity Matching System
+
+**Location**: [pkg/identity/identity.go](pkg/identity/identity.go)
+
+The framework provides legacy-compatible and modern identity matching:
+
+### Allowed Formats in Config
+
+```yaml
+allow_from:
+  - "29:abc123"              # Raw Teams user ID
+  - "teams:29:abc123"        # Canonical format
+  - "@alice"                 # Username format
+  - "29:abc123|alice"        # Compound format
+```
+
+### Matching Logic
+
+```go
+func MatchAllowed(sender bus.SenderInfo, allowed string) bool {
+	// 1. Try canonical "platform:id" first
+	if platform, id, ok := ParseCanonicalID(allowed); ok {
+		if sender.CanonicalID == BuildCanonicalID(platform, id) {
+			return true
+		}
+	}
+	
+	// 2. Fall back to PlatformID or Username
+	if sender.PlatformID == allowed { return true }
+	if sender.Username == "@" + allowed { return true }
+	
+	return false
+}
+```
+
+---
+
+## What a Teams Channel Implementation Would Need
+
+### Minimum Required Fields in InboundMessage
+
+```go
+InboundMessage{
+	Channel: "teams",
+	SenderID: userID,  // Teams: "29:uuid"
+	Sender: bus.SenderInfo{
+		Platform:    "teams",
+		PlatformID:  userID,  // "29:uuid"
+		CanonicalID: "teams:29:uuid",
+		Username:    userName,
+		DisplayName: displayName,
+	},
+	ChatID: conversationID,  // Teams ConversationReference.conversation_id
+	Content: messageContent,
+	Peer: bus.Peer{
+		Kind: "direct" || "channel",
+		ID: channelID || userID,
+	},
+	MessageID: activityID,  // Teams Activity ID
+	Metadata: map[string]string{
+		"team_id": teamID,
+		"channel_id": channelID,
+		"service_url": serviceURL,
+		// ... other Teams-specific fields
+	},
+}
+```
+
+### Routing Setup in Config
+
+```yaml
+agents:
+  routing:
+    - agent_id: "teams-agent"
+      match:
+        channel: "teams"
+        team_id: "team-xyz"        # Route by Teams Team ID
+```
+
+---
+
+## Key Takeaways for Teams + Foundry Integration
+
+1. **Framework is Ready**: GenericBus message structure can handle Teams IDs
+2. **ChatID is Primary**: Use Teams `ConversationReference.conversation_id` as ChatID for isolation
+3. **SessionKey Auto-Generated**: Routing + DMScope automatically creates session keys
+4. **Identity System Ready**: Canonical "teams:29:uuid" format supported
+5. **No Channel Implementation Yet**: Need to implement webhook receiver + message publisher
+6. **Foundry is Provider Only**: Currently only LLM backend, not messaging channel
+7. **User ID Format**: Teams uses `29:uuid` format - should populate both PlatformID and CanonicalID
+8. **Conversation Scope**: Teams conversation_id maps directly to InboundMessage.ChatID
+
+---
+
+## Reference Architecture Files
+
+| Component | File | Key Types |
+|-----------|------|-----------|
+| Bus Types | [pkg/bus/types.go](pkg/bus/types.go) | InboundMessage, SenderInfo, Peer |
+| Routing | [pkg/routing/route.go](pkg/routing/route.go) | RouteInput, ResolvedRoute |
+| Session Keys | [pkg/routing/session_key.go](pkg/routing/session_key.go) | SessionKeyParams, DM scopes |
+| Identity | [pkg/identity/identity.go](pkg/identity/identity.go) | BuildCanonicalID, MatchAllowed |
+| Agent Loop | [pkg/agent/loop.go](pkg/agent/loop.go) | Message processing, session isolation |
+| Example Channel | [pkg/channels/wecom/app.go](pkg/channels/wecom/app.go) | Channel implementation pattern |
diff --git a/TEAMS_QUICK_REFERENCE.md b/TEAMS_QUICK_REFERENCE.md
new file mode 100644
index 000000000..a789e1c34
--- /dev/null
+++ b/TEAMS_QUICK_REFERENCE.md
@@ -0,0 +1,315 @@
+# Quick Reference: Teams Integration Questions
+
+## Q1: Teams Channel Integration - Message Receiving & Processing
+
+**Status**: ❌ NOT IMPLEMENTED
+
+**Where it would go**: `pkg/channels/teams/` (currently doesn't exist)
+
+**Current Similar Implementation**: See [pkg/channels/wecom/app.go](pkg/channels/wecom/app.go) for webhook pattern
+
+**Expected Pattern**:
+1. HTTP webhook receiver on configured port
+2. Verify Teams Bot Framework signature
+3. Parse activity/message payload
+4. Build `InboundMessage` struct
+5. Publish to bus via `channel.HandleMessage()` or `messageBus.PublishInbound()`
+
+**Key Files to Reference**:
+- [pkg/channels/base.go](pkg/channels/base.go) - Base channel interface
+- [pkg/channels/manager.go](pkg/channels/manager.go) - Channel registration/lifecycle
+- [pkg/channels/wecom/app.go:605-650](pkg/channels/wecom/app.go#L605-L650) - HandleMessage pattern
+
+---
+
+## Q2: InboundMessage Structure - All Available Fields
+
+**Location**: [pkg/bus/types.go:18-35](pkg/bus/types.go#L18-L35)
+
+### Complete Field List
+
+| Field | Type | Purpose | Example |
+|-------|------|---------|---------|
+| `Channel` | string | Platform identifier | `"teams"` |
+| `SenderID` | string | Raw user ID | `"29:1ABC123"` |
+| `Sender` | SenderInfo | Structured identity | (see below) |
+| `Sender.Platform` | string | Platform name | `"teams"` |
+| `Sender.PlatformID` | string | User platform ID | `"29:1ABC123"` |
+| `Sender.CanonicalID` | string | **Normalized format** | `"teams:29:1abc123"` |
+| `Sender.Username` | string | Handle/username | `"alice"` |
+| `Sender.DisplayName` | string | Full display name | `"Alice Smith"` |
+| `ChatID` | string | **Conversation ID (PRIMARY)** | `"teams-conv-abc123"` |
+| `Content` | string | Message text | `"Hello world"` |
+| `Media` | []string | Media references | `["media://ref123"]` |
+| `Peer.Kind` | string | Peer type | `"direct"` \| `"channel"` |
+| `Peer.ID` | string | Peer ID | User/channel ID |
+| `MessageID` | string | Platform message ID | `"activity-123"` |
+| `MediaScope` | string | Media cleanup scope | `"teams:conv-abc123:msg-123"` |
+| `SessionKey` | string | **Session identifier** | `"agent:bot:teams:direct:29:abc123"` |
+| `Metadata` | map | Platform-specific data | (see below) |
+
+### Metadata Map (Platform-Specific)
+
+```go
+metadata := map[string]string{
+	"team_id":           "T12345",
+	"channel_id":        "C12345", 
+	"conversation_id":   "19:...",
+	"service_url":       "https://smba.trafficmanager.net/...",
+	"activity_id":       "...",
+	"from_user_id":      "29:...",
+	"from_user_name":    "alice",
+	"recipient_id":      "28:...",
+	"conversation_type": "personal|groupChat|channel",
+	"platform":          "teams",
+	// ... any other Teams-specific fields
+}
+```
+
+---
+
+## Q3: Unique User/Conversation ID Capture from Teams
+
+### What Teams Provides vs. What PicoClaw Needs
+
+**Teams → PicoClaw Mapping**:
+
+```
+Teams Activity Object
+├── from.id → SenderID (raw), Sender.PlatformID
+├── from.aadObjectId → (optional, use if available)
+├── conversation.id → ChatID (THE KEY FIELD)
+├── conversation.tenantId → Metadata["tenant_id"]
+├── channelData.teamsChannelId → Peer.ID (if channel)
+├── channelData.teamsTeamId → Metadata["team_id"], routing input
+├── serviceUrl → Metadata["service_url"]
+└── id → MessageID
+```
+
+### ID Construction
+
+**User Identity Chain**:
+```
+Teams: from.id = "29:U123ABC"
+  ↓
+Stored as: SenderID = "29:U123ABC"
+Stored as: Sender.PlatformID = "29:U123ABC"
+Normalized as: Sender.CanonicalID = "teams:29:u123abc" (lowercased)
+```
+
+**Conversation Identity Chain**:
+```
+Teams: conversation.id = "19:abc123@thread.v2"
+  ↓
+Stored as: ChatID = "19:abc123@thread.v2" (conversation scope)
+Used for: Session isolation, message routing, state persistence
+```
+
+**Team Identity Chain**:
+```
+Teams: channelData.teamsTeamId = "T12345678"
+  ↓
+Stored as: Metadata["team_id"] = "T12345678"
+  ↓
+Used in: Routing cascade (Level 4), agent selection
+```
+
+### Canonical ID Format
+
+Built by [pkg/identity/identity.go:BuildCanonicalID()](pkg/identity/identity.go#L11-L20):
+
+```go
+BuildCanonicalID("teams", "29:U123ABC")
+// Returns: "teams:29:u123abc" (normalized to lowercase)
+```
+
+**Used for**:
+- Access control matching
+- Cross-platform user linking (via identity_links in config)
+- User identity validation
+
+---
+
+## Q4: Foundry Agent Integration Points & ID Provision
+
+**Status**: ⚠️ PARTIAL - Foundry is an LLM Provider, NOT a Channel
+
+### Current Foundry Support
+
+**Location**: [pkg/providers/factory_provider.go:196](pkg/providers/factory_provider.go#L196)
+
+Foundry is integrated **only as LLM backend** (OpenAI-compatible API):
+
+```go
+case "azure-ai", "azure_foundry":
+    // Use for model calls, not messaging
+```
+
+**What Foundry Would Provide (if implemented as channel)**:
+- Foundry Agent service/conversation IDs
+- Foundry user session tracking
+- Foundry-specific message format
+
+**What's MISSING**:
+1. ❌ Foundry Agent channel receiver
+2. ❌ Foundry conversation → ChatID mapping
+3. ❌ Foundry agent ID → Agent routing
+
+### If Foundry Channel Were to Exist
+
+Expected `InboundMessage` would be:
+
+```go
+InboundMessage{
+	Channel: "foundry-agent",
+	SenderID: foundryUserID,
+	Sender: SenderInfo{
+		Platform:    "foundry",
+		PlatformID:  foundryUserID,
+		CanonicalID: "foundry:" + foundryUserID,
+		DisplayName: userName,
+	},
+	ChatID: foundryConversationID,  // Critical for isolation
+	Content: message,
+	Metadata: map[string]string{
+		"foundry_agent_id":         agentID,
+		"foundry_conversation_id":  conversationID,
+		"foundry_message_id":       messageID,
+		"platform":                 "foundry",
+		// ... other Foundry fields
+	},
+}
+```
+
+### Foundry ID Mapping Table (Hypothetical)
+
+| Foundry ID | InboundMessage Field | Purpose |
+|----------|----------------------|---------|
+| Agent ID | Routing/Config | Which agent handles |
+| User ID | SenderID | Who sent message |
+| Conversation ID | **ChatID** | Session isolation |
+| Message ID | MessageID | For threading |
+| Service Endpoint | Metadata | For API calls |
+
+---
+
+## Q5: How ChatID is Currently Used for Session ID Association
+
+**Location**: [pkg/agent/loop.go:1248-1270](pkg/agent/loop.go#L1248-L1270)
+
+### ChatID → SessionKey Conversion
+
+**Process**:
+
+```
+1. InboundMessage arrives with ChatID
+   ↓
+2. Router resolves agent (via RouteInput)
+   ↓
+3. SessionKey built from:
+   - Agent ID
+   - Channel name
+   - Peer information (ChatID wrapped as Peer.ID)
+   - DMScope configuration
+   ↓
+4. Result: SessionKey = "agent:botname:team:type:id"
+   ↓
+5. SessionKey used to find/create workspace & history
+```
+
+### Session Key Patterns by DMScope
+
+**From config `session.dm_scope`**:
+
+| Setting | Session Behavior | Key Format |
+|---------|------------------|-----------|
+| Not set / `main` | Single shared session | `agent:bot:main` |
+| `per_peer` | One session per user | `agent:bot:direct:user123` |
+| `per_channel_peer` | One per channel+user | `agent:bot:teams:direct:user123` |
+| `per_account_channel_peer` | One per account+channel+user | `agent:bot:teams:act1:direct:user123` |
+
+**Code Reference**: [pkg/routing/session_key.go:40-100](pkg/routing/session_key.go#L40-L100)
+
+### Session Isolation via ChatID
+
+When ChatID is unique and non-"direct":
+
+```go
+// From pkg/agent/loop.go:1248-1270
+if isolationID != "" && isolationID != "direct" {
+	// Creates isolated agent instance with separate:
+	// - Workspace directory
+	// - Session history
+	// - Memory storage
+	// - State
+	agent = NewAgentInstance(ac, cfg, baseAgent.Provider, isolationID)
+}
+```
+
+**Isolation Example**:
+
+```
+ChatID = "teams-channel-abc123"
+  ↓
+Creates: workspace/teams-channel-abc123/
+  ├── sessions/
+  ├── memory/
+  ├── skills/
+  └── state/
+  ↓
+Each channel conversation has completely isolated history
+```
+
+### State Persistence
+
+Tracks last ChatID:
+
+```go
+// Record last chat for workspace continuity
+al.RecordLastChatID(chatID)  // pkg/agent/loop.go
+```
+
+Stored in: `workspace/state/state.json`:
+```json
+{
+  "last_channel": "teams",
+  "last_chat_id": "19:abc123@thread.v2",
+  "timestamp": "2025-03-26T10:00:00Z"
+}
+```
+
+---
+
+## Summary Table: ID Field Mapping
+
+| Concept | Field | Example | Used For |
+|---------|-------|---------|----------|
+| **User** | `SenderID` + `Sender.PlatformID` | `"29:U123ABC"` | Message author |
+| **User (Normalized)** | `Sender.CanonicalID` | `"teams:29:u123abc"` | Access control |
+| **Conversation** | `ChatID` | `"19:abc123@thread.v2"` | **Session isolation** |
+| **Team** | `Metadata["team_id"]` | `"T12345678"` | Agent routing level |
+| **Channel** | `Peer.Kind` + `Peer.ID` | `"channel:C12345"` | Routing peer |
+| **Message** | `MessageID` | `"activity-123"` | Threading, dedup |
+| **Workspace** | Derived from ChatID | `workspace/19:abc123@thread.v2/` | Data isolation |
+| **Session** | `SessionKey` | `"agent:bot:teams:direct:29:u123abc"` | History tracking |
+
+---
+
+## File Cross-References
+
+### For Teams Implementation
+- Start: [pkg/channels/manager.go](pkg/channels/manager.go) - Channel registration
+- Reference: [pkg/channels/wecom/app.go](pkg/channels/wecom/app.go) - Full implementation pattern  
+- Base: [pkg/channels/base.go](pkg/channels/base.go) - Handler interface
+
+### For Routing/Session
+- Routing: [pkg/routing/route.go](pkg/routing/route.go) - 7-level cascade
+- Keys: [pkg/routing/session_key.go](pkg/routing/session_key.go) - Key building
+- Isolation: [pkg/agent/loop.go:1248+](pkg/agent/loop.go#L1248) - ChatID isolation
+
+### For Identity
+- Identity: [pkg/identity/identity.go](pkg/identity/identity.go) - CanonicalID logic
+- Matching: Lines 28-100 - Access control matching
+
+### For State
+- State: [pkg/state/state.go](pkg/state/state.go) - LastChatID persistence
diff --git a/cmd/picoclaw/internal/onboard/command.go b/cmd/picoclaw/internal/onboard/command.go
index 4be19b2a5..eeae4b879 100644
--- a/cmd/picoclaw/internal/onboard/command.go
+++ b/cmd/picoclaw/internal/onboard/command.go
@@ -12,6 +12,7 @@ var embeddedFiles embed.FS
 
 func NewOnboardCommand() *cobra.Command {
 	var encrypt bool
+	var yes bool
 
 	cmd := &cobra.Command{
 		Use:     "onboard",
@@ -20,15 +21,19 @@ func NewOnboardCommand() *cobra.Command {
 		// Run without subcommands → original onboard flow
 		Run: func(cmd *cobra.Command, args []string) {
 			if len(args) == 0 {
-				onboard(encrypt)
+				onboard(encrypt, yes)
 			} else {
 				_ = cmd.Help()
 			}
 		},
 	}
 
+	cmd.AddCommand(NewPurgeCommand())
+
 	cmd.Flags().BoolVar(&encrypt, "enc", false,
 		"Enable credential encryption (generates SSH key and prompts for passphrase)")
+	cmd.Flags().BoolVarP(&yes, "yes", "y", false,
+		"Assume 'yes' for all prompts (useful for scripts/Docker non-TTY builds)")
 
 	return cmd
 }
diff --git a/cmd/picoclaw/internal/onboard/helpers.go b/cmd/picoclaw/internal/onboard/helpers.go
index 626698fec..3b7587dc2 100644
--- a/cmd/picoclaw/internal/onboard/helpers.go
+++ b/cmd/picoclaw/internal/onboard/helpers.go
@@ -13,7 +13,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/credential"
 )
 
-func onboard(encrypt bool) {
+func onboard(encrypt bool, yes bool) {
 	configPath := internal.GetConfigPath()
 
 	configExists := false
@@ -26,12 +26,14 @@ func onboard(encrypt bool) {
 			if _, err := os.Stat(sshKeyPath); err == nil {
 				// Both exist — confirm a full reset.
 				fmt.Printf("Config already exists at %s\n", configPath)
-				fmt.Print("Overwrite config with defaults? (y/n): ")
-				var response string
-				fmt.Scanln(&response)
-				if response != "y" {
-					fmt.Println("Aborted.")
-					return
+				if !yes {
+					fmt.Print("Overwrite config with defaults? (y/n): ")
+					var response string
+					fmt.Scanln(&response)
+					if response != "y" {
+						fmt.Println("Aborted.")
+						return
+					}
 				}
 				configExists = false // user agreed to reset; treat as fresh
 			}
@@ -54,7 +56,7 @@ func onboard(encrypt bool) {
 		// the current process and disappears when it exits.
 		os.Setenv(credential.PassphraseEnvVar, passphrase)
 
-		if err = setupSSHKey(); err != nil {
+		if err = setupSSHKey(yes); err != nil {
 			fmt.Printf("Error generating SSH key: %v\n", err)
 			os.Exit(1)
 		}
@@ -134,7 +136,7 @@ func promptPassphrase() (string, error) {
 // setupSSHKey generates the picoclaw-specific SSH key at ~/.ssh/picoclaw_ed25519.key.
 // If the key already exists the user is warned and asked to confirm overwrite.
 // Answering anything other than "y" keeps the existing key (not an error).
-func setupSSHKey() error {
+func setupSSHKey(yes bool) error {
 	keyPath, err := credential.DefaultSSHKeyPath()
 	if err != nil {
 		return fmt.Errorf("cannot determine SSH key path: %w", err)
@@ -143,12 +145,14 @@ func setupSSHKey() error {
 	if _, err := os.Stat(keyPath); err == nil {
 		fmt.Printf("\n⚠️  WARNING: %s already exists.\n", keyPath)
 		fmt.Println("    Overwriting will invalidate any credentials previously encrypted with this key.")
-		fmt.Print("    Overwrite? (y/n): ")
-		var response string
-		fmt.Scanln(&response)
-		if response != "y" {
-			fmt.Println("Keeping existing SSH key.")
-			return nil
+		if !yes {
+			fmt.Print("    Overwrite? (y/n): ")
+			var response string
+			fmt.Scanln(&response)
+			if response != "y" {
+				fmt.Println("Keeping existing SSH key.")
+				return nil
+			}
 		}
 	}
 
diff --git a/cmd/picoclaw/internal/onboard/purge.go b/cmd/picoclaw/internal/onboard/purge.go
new file mode 100644
index 000000000..456ee22db
--- /dev/null
+++ b/cmd/picoclaw/internal/onboard/purge.go
@@ -0,0 +1,58 @@
+package onboard
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func NewPurgeCommand() *cobra.Command {
+	var force bool
+
+	cmd := &cobra.Command{
+		Use:   "purge",
+		Short: "Delete the picoclaw workspace and logs",
+		Long:  "Completely deletes the .picoclaw/workspace and .picoclaw/logs directories. Use with caution.",
+		Run: func(cmd *cobra.Command, args []string) {
+			home := internal.GetPicoclawHome()
+			workspace := filepath.Join(home, "workspace")
+			logs := filepath.Join(home, "logs")
+
+			fmt.Printf("This will delete:\n  - %s\n  - %s\n", workspace, logs)
+
+			if !force {
+				fmt.Print("Are you sure? (y/n): ")
+				var response string
+				fmt.Scanln(&response)
+				if response != "y" {
+					fmt.Println("Aborted.")
+					return
+				}
+			}
+
+			fmt.Println("Purging...")
+			
+			if err := os.RemoveAll(workspace); err != nil {
+				fmt.Printf("Error deleting workspace: %v\n", err)
+			} else {
+				fmt.Println("✓ Workspace deleted")
+			}
+
+			if err := os.RemoveAll(logs); err != nil {
+				fmt.Printf("Error deleting logs: %v\n", err)
+			} else {
+				fmt.Println("✓ Logs deleted")
+			}
+			
+			fmt.Println("Purge complete.")
+		},
+	}
+
+	cmd.Flags().BoolVarP(&force, "force", "f", false, "Skip confirmation prompt")
+
+	return cmd
+}
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
index 631238cb6..0f20f79b4 100644
--- a/pkg/gateway/gateway.go
+++ b/pkg/gateway/gateway.go
@@ -129,6 +129,7 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 		logger.SetLevelFromString(config.ResolveGatewayLogLevel(configPath))
 	}
 
+<<<<<<< HEAD
 	cfg, err := config.LoadConfig(configPath)
 	if err != nil {
 		logger.Fatalf("error loading config: %v", err)
@@ -155,10 +156,15 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 	}
 	defer pid.RemovePidFile(homePath)
 
+=======
+	fmt.Printf("🔍 Creating startup provider for model: %s (allow empty: %v)\n", cfg.Agents.Defaults.GetModelName(), allowEmptyStartup)
+>>>>>>> 46dc6e5 (Synchronize hardening: added onboard purge, non-interactive mode, and diagnostic startup logs)
 	provider, modelID, err := createStartupProvider(cfg, allowEmptyStartup)
 	if err != nil {
+		fmt.Printf("❌ Error creating provider: %v\n", err)
 		return fmt.Errorf("error creating provider: %w", err)
 	}
+	fmt.Printf("✓ Provider created (Model ID: %s)\n", modelID)
 
 	if modelID != "" {
 		cfg.Agents.Defaults.ModelName = modelID
@@ -181,11 +187,14 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 			"skills_available": skillsInfo["available"],
 		})
 
+	fmt.Println("🚀 Setting up services...")
 	runningServices, err := setupAndStartServices(cfg, agentLoop, msgBus, pidData.Token)
 	if err != nil {
+		fmt.Printf("❌ Error starting services: %v\n", err)
 		return err
 	}
 
+
 	// Setup manual reload channel for /reload endpoint
 	manualReloadChan := make(chan struct{}, 1)
 	runningServices.manualReloadChan = manualReloadChan

From 5ca9b1c349436ada3a0c2a3409edbb7268f3b7cb Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Fri, 3 Apr 2026 21:35:55 +0200
Subject: [PATCH 11/25] Remove deprecated /cgat and loop detection endpoints
 from server and docs

---
 README.md                                     |   2 +
 cmd/picoclaw/internal/onboard/command_test.go |   7 +-
 cmd/picoclaw/internal/onboard/purge.go        |   4 +-
 cmd/picoclaw/main.go                          |   1 +
 config/config.json.azure                      | 568 ++++++++++++++++++
 docker/Dockerfile.full                        |  13 +-
 docs/api.md                                   |   6 +-
 docs/configuration.md                         |  29 +-
 docs/docker.md                                |  15 +
 docs/tools_configuration.md                   |  28 +
 pkg/agent/instance.go                         |  14 +-
 pkg/agent/instance_test.go                    |   4 +-
 pkg/agent/loop.go                             |  15 +-
 pkg/agent/loop_mcp.go                         | 197 +++---
 pkg/agent/multiuser_mcp_test.go               |  55 ++
 pkg/config/config.go                          |  60 +-
 pkg/config/config_old.go                      |   9 +-
 pkg/config/config_struct.go                   |  16 +-
 pkg/config/gateway.go                         |   1 -
 pkg/gateway/gateway.go                        |  38 +-
 pkg/health/server.go                          |  17 +-
 pkg/logger/panic.go                           |   2 +-
 pkg/logger/panic_unix.go                      |   7 +-
 pkg/providers/factory_provider.go             |   3 +-
 pkg/providers/http_provider.go                |  10 +-
 pkg/providers/openai_compat/provider.go       |  31 +-
 pkg/tools/edit.go                             |  20 +-
 pkg/tools/edit_test.go                        |  30 +-
 pkg/tools/filesystem.go                       | 143 ++++-
 pkg/tools/filesystem_test.go                  |  97 ++-
 pkg/tools/registry.go                         |  18 +-
 pkg/tools/registry_test.go                    |  39 ++
 pkg/tools/send_file.go                        |  18 +-
 web/backend/api/skills.go                     |   2 +-
 34 files changed, 1227 insertions(+), 292 deletions(-)
 create mode 100644 config/config.json.azure
 create mode 100644 pkg/agent/multiuser_mcp_test.go

diff --git a/README.md b/README.md
index 09aebcdff..30f965c87 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,8 @@
 
 🧠 **Smart routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs.
 
+🛡️ **Hardened Multi-User Isolation**: Built-in [Tenant Isolation](docs/configuration.md#🔒-multi-tenant-agent-isolation) for shared infrastructure (Azure/ACA) — automatically partitions workspaces, memory, and tools (including MCP) per-user session.
+
 _*Recent builds may use 10-20MB due to rapid PR merges. Resource optimization is planned. Boot speed comparison based on 0.8GHz single-core benchmarks (see table below)._
 
 <div align="center">
diff --git a/cmd/picoclaw/internal/onboard/command_test.go b/cmd/picoclaw/internal/onboard/command_test.go
index 56936190b..eb2c57f3d 100644
--- a/cmd/picoclaw/internal/onboard/command_test.go
+++ b/cmd/picoclaw/internal/onboard/command_test.go
@@ -28,5 +28,10 @@ func TestNewOnboardCommand(t *testing.T) {
 	encFlag := cmd.Flags().Lookup("enc")
 	require.NotNil(t, encFlag, "expected --enc flag to be registered")
 	assert.Equal(t, "false", encFlag.DefValue, "--enc should default to false")
-	assert.False(t, cmd.HasSubCommands())
+	yesFlag := cmd.Flags().Lookup("yes")
+	require.NotNil(t, yesFlag, "expected --yes flag to be registered")
+	assert.Equal(t, "false", yesFlag.DefValue, "--yes should default to false")
+	assert.True(t, cmd.HasSubCommands())
+	assert.Len(t, cmd.Commands(), 1)
+	assert.Equal(t, "purge", cmd.Commands()[0].Name())
 }
diff --git a/cmd/picoclaw/internal/onboard/purge.go b/cmd/picoclaw/internal/onboard/purge.go
index 456ee22db..76138e0f4 100644
--- a/cmd/picoclaw/internal/onboard/purge.go
+++ b/cmd/picoclaw/internal/onboard/purge.go
@@ -35,7 +35,7 @@ func NewPurgeCommand() *cobra.Command {
 			}
 
 			fmt.Println("Purging...")
-			
+
 			if err := os.RemoveAll(workspace); err != nil {
 				fmt.Printf("Error deleting workspace: %v\n", err)
 			} else {
@@ -47,7 +47,7 @@ func NewPurgeCommand() *cobra.Command {
 			} else {
 				fmt.Println("✓ Logs deleted")
 			}
-			
+
 			fmt.Println("Purge complete.")
 		},
 	}
diff --git a/cmd/picoclaw/main.go b/cmd/picoclaw/main.go
index 434917c0b..57c303501 100644
--- a/cmd/picoclaw/main.go
+++ b/cmd/picoclaw/main.go
@@ -86,6 +86,7 @@ func main() {
 
 	cmd := NewPicoclawCommand()
 	if err := cmd.Execute(); err != nil {
+		fmt.Fprintf(os.Stderr, "\n❌ FATAL: %v\n", err)
 		os.Exit(1)
 	}
 }
diff --git a/config/config.json.azure b/config/config.json.azure
new file mode 100644
index 000000000..9a7ff3397
--- /dev/null
+++ b/config/config.json.azure
@@ -0,0 +1,568 @@
+{
+  "session": {
+    "dm_scope": "per-channel-peer"
+  },
+  "version": 1,
+  "agents": {
+    "defaults": {
+      "workspace": "",
+      "restrict_to_workspace": true,
+      "allow_read_outside_workspace": false,
+      "provider": "openai",
+      "model_name": "azure-grok",
+      "max_tokens": 32768,
+      "max_tool_iterations": 50,
+      "summarize_message_threshold": 20,
+      "summarize_token_percent": 75,
+      "steering_mode": "one-at-a-time",
+      "subturn": {
+        "max_depth": 10,
+        "max_concurrent": 5,
+        "default_timeout_minutes": 20,
+        "default_token_budget": 100000,
+        "concurrency_timeout_sec": 10
+      },
+      "tool_feedback": {
+        "enabled": true,
+        "max_args_length": 300
+      }
+    }
+  },
+  "channels": {
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": [],
+      "reasoning_channel_id": ""
+    },
+    "telegram": {
+      "enabled": false,
+      "base_url": "",
+      "proxy": "",
+      "allow_from": [],
+      "group_trigger": {},
+      "typing": {
+        "enabled": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking... 💭"
+      },
+      "streaming": {
+        "enabled": true,
+        "throttle_seconds": 3,
+        "min_growth_chars": 200
+      },
+      "reasoning_channel_id": "",
+      "use_markdown_v2": false
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "",
+      "allow_from": [],
+      "group_trigger": {},
+      "placeholder": {},
+      "reasoning_channel_id": "",
+      "random_reaction_emoji": null,
+      "is_lark": false
+    },
+    "discord": {
+      "enabled": false,
+      "proxy": "",
+      "allow_from": [],
+      "mention_only": false,
+      "group_trigger": {},
+      "typing": {},
+      "placeholder": {},
+      "reasoning_channel_id": ""
+    },
+    "maixcam": {
+      "enabled": false,
+      "host": "0.0.0.0",
+      "port": 18790,
+      "allow_from": [],
+      "reasoning_channel_id": ""
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "allow_from": [],
+      "group_trigger": {},
+      "max_message_length": 2000,
+      "max_base64_file_size_mib": 0,
+      "send_markdown": false,
+      "reasoning_channel_id": ""
+    },
+    "dingtalk": {
+      "enabled": false,
+      "client_id": "",
+      "allow_from": [],
+      "group_trigger": {},
+      "reasoning_channel_id": ""
+    },
+    "slack": {
+      "enabled": false,
+      "allow_from": [],
+      "group_trigger": {},
+      "typing": {},
+      "placeholder": {},
+      "reasoning_channel_id": ""
+    },
+    "matrix": {
+      "enabled": false,
+      "homeserver": "https://matrix.org",
+      "user_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking... 💭"
+      },
+      "reasoning_channel_id": ""
+    },
+    "line": {
+      "enabled": false,
+      "webhook_host": "0.0.0.0",
+      "webhook_port": 18791,
+      "webhook_path": "/webhook/line",
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "typing": {},
+      "placeholder": {},
+      "reasoning_channel_id": ""
+    },
+    "onebot": {
+      "enabled": false,
+      "ws_url": "ws://127.0.0.1:3001",
+      "reconnect_interval": 5,
+      "group_trigger_prefix": null,
+      "allow_from": [],
+      "group_trigger": {},
+      "typing": {},
+      "placeholder": {},
+      "reasoning_channel_id": ""
+    },
+    "wecom": {
+      "enabled": false,
+      "webhook_url": "",
+      "webhook_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": [],
+      "reply_timeout": 5,
+      "group_trigger": {},
+      "reasoning_channel_id": ""
+    },
+    "wecom_app": {
+      "enabled": false,
+      "corp_id": "",
+      "agent_id": 0,
+      "webhook_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5,
+      "group_trigger": {},
+      "reasoning_channel_id": ""
+    },
+    "wecom_aibot": {
+      "enabled": false,
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "reply_timeout": 5,
+      "max_steps": 10,
+      "welcome_message": "Hello! I'm your AI assistant. How can I help you today?",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly.",
+      "reasoning_channel_id": ""
+    },
+    "weixin": {
+      "enabled": false,
+      "base_url": "https://ilinkai.weixin.qq.com/",
+      "cdn_base_url": "https://novac2c.cdn.weixin.qq.com/c2c",
+      "proxy": "",
+      "allow_from": [],
+      "reasoning_channel_id": ""
+    },
+    "pico": {
+      "enabled": false,
+      "ping_interval": 30,
+      "read_timeout": 60,
+      "write_timeout": 10,
+      "max_connections": 100,
+      "allow_from": [],
+      "placeholder": {}
+    },
+    "pico_client": {
+      "enabled": false,
+      "url": "",
+      "token": "",
+      "allow_from": null
+    },
+    "irc": {
+      "enabled": false,
+      "server": "",
+      "tls": false,
+      "nick": "",
+      "sasl_user": "",
+      "channels": null,
+      "allow_from": null,
+      "group_trigger": {},
+      "typing": {},
+      "reasoning_channel_id": ""
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api.openai.com/v1"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_base": "https://api.anthropic.com/v1"
+    },
+    {
+      "model_name": "deepseek-chat",
+      "model": "deepseek/deepseek-chat",
+      "api_base": "https://api.deepseek.com/v1"
+    },
+    {
+      "model_name": "gemini-2.0-flash",
+      "model": "gemini/gemini-2.0-flash-exp",
+      "api_base": "https://generativelanguage.googleapis.com/v1beta"
+    },
+    {
+      "model_name": "qwen-plus",
+      "model": "qwen/qwen-plus",
+      "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+    },
+    {
+      "model_name": "moonshot-v1-8k",
+      "model": "moonshot/moonshot-v1-8k",
+      "api_base": "https://api.moonshot.cn/v1"
+    },
+    {
+      "model_name": "llama-3.3-70b",
+      "model": "groq/llama-3.3-70b-versatile",
+      "api_base": "https://api.groq.com/openai/v1"
+    },
+    {
+      "model_name": "openrouter-auto",
+      "model": "openrouter/auto",
+      "api_base": "https://openrouter.ai/api/v1"
+    },
+    {
+      "model_name": "openrouter-gpt-5.4",
+      "model": "openrouter/openai/gpt-5.4",
+      "api_base": "https://openrouter.ai/api/v1"
+    },
+    {
+      "model_name": "nemotron-4-340b",
+      "model": "nvidia/nemotron-4-340b-instruct",
+      "api_base": "https://integrate.api.nvidia.com/v1"
+    },
+    {
+      "model_name": "azure-grok",
+      "model": "openai/grok-4-fast-non-reasoning",
+      "api_base": "https://TestSJF.openai.azure.com/openai/v1/",
+      "api_key": "REDACTED"
+    },
+    {
+      "model_name": "cerebras-llama-3.3-70b",
+      "model": "cerebras/llama-3.3-70b",
+      "api_base": "https://api.cerebras.ai/v1"
+    },
+    {
+      "model_name": "vivgrid-auto",
+      "model": "vivgrid/auto",
+      "api_base": "https://api.vivgrid.com/v1"
+    },
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_base": "https://ark.cn-beijing.volces.com/api/v3"
+    },
+    {
+      "model_name": "doubao-pro",
+      "model": "volcengine/doubao-pro-32k",
+      "api_base": "https://ark.cn-beijing.volces.com/api/v3"
+    },
+    {
+      "model_name": "deepseek-v3",
+      "model": "shengsuanyun/deepseek-v3",
+      "api_base": "https://api.shengsuanyun.com/v1"
+    },
+    {
+      "model_name": "gemini-flash",
+      "model": "antigravity/gemini-3-flash",
+      "auth_method": "oauth"
+    },
+    {
+      "model_name": "copilot-gpt-5.4",
+      "model": "github-copilot/gpt-5.4",
+      "api_base": "http://localhost:4321",
+      "auth_method": "oauth"
+    },
+    {
+      "model_name": "llama3",
+      "model": "ollama/llama3",
+      "api_base": "http://localhost:11434/v1"
+    },
+    {
+      "model_name": "mistral-small",
+      "model": "mistral/mistral-small-latest",
+      "api_base": "https://api.mistral.ai/v1"
+    },
+    {
+      "model_name": "deepseek-v3.2",
+      "model": "avian/deepseek/deepseek-v3.2",
+      "api_base": "https://api.avian.io/v1"
+    },
+    {
+      "model_name": "kimi-k2.5",
+      "model": "avian/moonshotai/kimi-k2.5",
+      "api_base": "https://api.avian.io/v1"
+    },
+    {
+      "model_name": "MiniMax-M2.5",
+      "model": "minimax/MiniMax-M2.5",
+      "api_base": "https://api.minimaxi.com/v1",
+      "extra_body": {
+        "reasoning_split": true
+      }
+    },
+    {
+      "model_name": "LongCat-Flash-Thinking",
+      "model": "longcat/LongCat-Flash-Thinking",
+      "api_base": "https://api.longcat.chat/openai"
+    },
+    {
+      "model_name": "modelscope-qwen",
+      "model": "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
+      "api_base": "https://api-inference.modelscope.cn/v1"
+    },
+    {
+      "model_name": "local-model",
+      "model": "vllm/custom-model",
+      "api_base": "http://localhost:8000/v1"
+    },
+    {
+      "model_name": "azure-gpt5",
+      "model": "azure/my-gpt5-deployment",
+      "api_base": "https://your-resource.openai.azure.com"
+    }
+  ],
+  "gateway": {
+    "host": "0.0.0.0",
+    "port": 18790,
+    "chat_enabled": true,
+    "hot_reload": true,
+    "log_level": "info",
+    "api_key": "picoclaw-secret-123"
+  },
+  "hooks": {
+    "enabled": true,
+    "defaults": {
+      "observer_timeout_ms": 500,
+      "interceptor_timeout_ms": 5000,
+      "approval_timeout_ms": 60000
+    }
+  },
+  "tools": {
+    "filter_sensitive_data": true,
+    "filter_min_length": 8,
+    "allow_read_paths": null,
+    "allow_write_paths": null,
+    "deny_read_paths": [
+      "^skills(/.*)?$"
+    ],
+    "deny_write_paths": [
+      "^skills(/.*)?$"
+    ],
+    "web": {
+      "enabled": true,
+      "brave": {
+        "enabled": false,
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "base_url": "",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "",
+        "max_results": 5
+      },
+      "glm_search": {
+        "enabled": false,
+        "base_url": "https://open.bigmodel.cn/api/paas/v4/web_search",
+        "search_engine": "search_std",
+        "max_results": 5
+      },
+      "baidu_search": {
+        "enabled": false,
+        "base_url": "https://qianfan.baidubce.com/v2/ai_search/web_search",
+        "max_results": 10
+      },
+      "prefer_native": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext"
+    },
+    "cron": {
+      "enabled": true,
+      "exec_timeout_minutes": 5,
+      "allow_command": true
+    },
+    "exec": {
+      "enabled": true,
+      "enable_deny_patterns": true,
+      "allow_remote": true,
+      "custom_deny_patterns": null,
+      "custom_allow_patterns": null,
+      "timeout_seconds": 60
+    },
+    "skills": {
+      "whitelist_enabled": true,
+      "whitelist": [
+        "weather",
+        "summarize"
+      ],
+      "enabled": true,
+      "registries": {
+        "clawhub": {
+          "enabled": true,
+          "base_url": "https://clawhub.ai",
+          "search_path": "",
+          "skills_path": "",
+          "download_path": "",
+          "timeout": 0,
+          "max_zip_size": 0,
+          "max_response_size": 0
+        }
+      },
+      "github": {},
+      "max_concurrent_searches": 2,
+      "search_cache": {
+        "max_size": 50,
+        "ttl_seconds": 300
+      }
+    },
+    "media_cleanup": {
+      "enabled": true,
+      "max_age_minutes": 30,
+      "interval_minutes": 5
+    },
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": false,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {}
+    },
+    "whitelist": [
+      "spawn",
+      "subagent",
+      "read_file",
+      "list_dir",
+      "write_file",
+      "edit_file",
+      "append_file",
+      "message",
+      "weather",
+      "summarize",
+      "github",
+      "search_tool"
+    ],
+    "whitelist_enabled": true,
+    "append_file": {
+      "enabled": true
+    },
+    "edit_file": {
+      "enabled": true
+    },
+    "find_skills": {
+      "enabled": true
+    },
+    "i2c": {
+      "enabled": false
+    },
+    "install_skill": {
+      "enabled": true
+    },
+    "list_dir": {
+      "enabled": true
+    },
+    "message": {
+      "enabled": true
+    },
+    "read_file": {
+      "enabled": true,
+      "max_read_file_size": 65536
+    },
+    "send_file": {
+      "enabled": true
+    },
+    "spawn": {
+      "enabled": true
+    },
+    "spawn_status": {
+      "enabled": false
+    },
+    "spi": {
+      "enabled": false
+    },
+    "subagent": {
+      "enabled": true
+    },
+    "web_fetch": {
+      "enabled": true
+    },
+    "write_file": {
+      "enabled": true
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  },
+  "devices": {
+    "enabled": false,
+    "monitor_usb": true
+  },
+  "voice": {
+    "echo_transcription": false
+  },
+  "build_info": {
+    "version": "0.1.0",
+    "git_commit": "054b55fd",
+    "build_time": "2026-03-23T10:15:13+0100",
+    "go_version": "go1.26.1"
+  }
+}
\ No newline at end of file
diff --git a/docker/Dockerfile.full b/docker/Dockerfile.full
index 30e1680d5..aa85ee4cc 100644
--- a/docker/Dockerfile.full
+++ b/docker/Dockerfile.full
@@ -37,7 +37,18 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
 # Copy binary
 COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
 
-# Create picoclaw home directory
+# Create non-root user and group
+# node image already has a 'node' user with UID 1000, so we remove it first
+RUN deluser --remove-home node || true && \
+    addgroup -g 1000 picoclaw && \
+    adduser -D -u 1000 -G picoclaw picoclaw
+
+# Switch to non-root user
+USER picoclaw
+WORKDIR /home/picoclaw
+
+# Run onboard to create initial directories and config
+# HOME will be /home/picoclaw
 RUN /usr/local/bin/picoclaw onboard
 
 ENTRYPOINT ["picoclaw"]
diff --git a/docs/api.md b/docs/api.md
index af59081cd..1c46a428a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -6,13 +6,13 @@ By default, the gateway listens on `127.0.0.1:18790`.
 
 ## 💬 Chat API
 
-The `/chat` (and alias `/cgat`) endpoint allows you to interact with the PicoClaw agent via a simple HTTP interface. This API is designed to be **asynchronous** to avoid timeouts during long-running LLM tasks or tool executions.
+The `/chat` endpoint allows you to interact with the PicoClaw agent via a simple HTTP interface. This API is designed to be **asynchronous** to avoid timeouts during long-running LLM tasks or tool executions.
 
 ### 1. Initiate a Chat Session (POST)
 
 Start a new chat request.
 
-**Endpoint:** `POST /chat` (or `POST /cgat`)  
+**Endpoint:** `POST /chat`  
 **Content-Type:** `application/json`
 
 **Request Body:**
@@ -35,7 +35,7 @@ Start a new chat request.
 
 Retrieve the status and response of a previously initiated session.
 
-**Endpoint:** `GET /chat?session_id=<ID>` (or `GET /cgat?session_id=<ID>`)
+**Endpoint:** `GET /chat?session_id=<ID>`
 
 **Possible Responses:**
 
diff --git a/docs/configuration.md b/docs/configuration.md
index e94374160..fc1cc061b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -77,7 +77,7 @@ When an incoming message includes a **ChatID** (passed in the `/chat` API or ext
  
 1.  **Isolated Workspace:** The agent's operations are restricted to `workspace/sessions/{isolationID}/workspace`.
 2.  **Isolated Memory:** Long-term memory (`MEMORY.md`) is stored and read from the isolated session path.
-3.  **Isolated Tools:** Tools like `read_file` and `write_file` are automatically pointed to the isolated workspace, preventing any tenant from accessing another's files or the global base workspace.
+3.  **Isolated Tools:** Tools like `read_file` and `write_file` are automatically pointed to the isolated workspace. Additionally, **MCP server tools** (e.g., Harvest, Monday) and discovery search tools are dynamically registered to each isolated instance, ensuring they inherit the same security boundaries.
  
 #### Tenant Identification (Inbound Integration)
  
@@ -98,6 +98,33 @@ If no `ChatID` is detected, the request is routed to the **Global Agent** contex
 -   **Session Agents:** Every request with a `chatID` creates a transient isolated agent instance that "routes" all file and memory operations into its session-specific subdirectory.
  
 This mechanism is transparent to the end-user and the AI agent itself, ensuring a secure and portable multi-user environment out-of-the-box.
+
+### 🚀 Onboarding & Automation
+
+For automated deployments (like Azure Container Apps or CI/CD), the `onboard` command supports non-interactive execution and environment cleanup.
+
+#### Automated Setup
+
+Use the `--yes` (or `-y`) flag to skip all interactive prompts and automatically generate default credentials/keys:
+
+```bash
+picoclaw onboard --yes
+```
+
+#### Environment Purge
+
+If you need to reset an environment (e.g., before a clean redeploy), use the `purge` subcommand. This removes existing workspaces, logs, and generated keys:
+
+```bash
+# Safe purge (checks if files exist)
+picoclaw onboard purge
+
+# Force purge (no confirmation)
+picoclaw onboard purge --force
+```
+
+> [!WARNING]
+> The `purge` command is destructive. It will delete your local session history, memory, and encrypted secrets. Only use it when you are prepared to start from a clean slate.
  
 ### Skill Sources
 
diff --git a/docs/docker.md b/docs/docker.md
index 6c32879a6..69cff013b 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -67,6 +67,21 @@ docker compose -f docker/docker-compose.yml pull
 docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
+### 🔒 Hardened & Non-Root Deployment
+
+For production environments (like Azure Container Apps or Kubernetes), use the **full hardened image** (`docker/Dockerfile.full`).
+
+This image provides several security and reliability enhancements:
+- **Non-Root Execution**: Runs as the `picoclaw` user (UID 1000) instead of root, meeting strict security requirements.
+- **Volume Compatibility**: Fixed UID 1000 ensures compatibility with Azure Files and other cloud volume mounts without manual `chown` hacks.
+- **Self-Contained**: Includes the full system suite (Node.js, Python, etc.) required for all tools.
+- **Automated Onboarding**: The image entrypoint automatically triggers `picoclaw onboard --yes` if the environment is not initialized.
+
+To build it manually:
+```bash
+docker build -f docker/Dockerfile.full -t picoclaw-full:latest .
+```
+
 ### 🚀 Quick Start
 
 > [!TIP]
diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md
index adee9244a..6947ac8af 100644
--- a/docs/tools_configuration.md
+++ b/docs/tools_configuration.md
@@ -37,6 +37,34 @@ See [Sensitive Data Filtering](../sensitive_data_filtering.md) for full document
 | `filter_sensitive_data` | bool | `true` | Enable/disable filtering |
 | `filter_min_length` | int | `8` | Minimum content length to trigger filtering |
 
+## File Paths & Workspace Security
+
+PicoClaw provides path-level security for all filesystem-related tools (`read_file`, `write_file`, `list_dir`, `edit_file`, `append_file`). This allows you to restrict the agent's access to specific patterns or block sensitive directories (like a `skills/` folder) even if they are inside the workspace.
+
+| Config | Type | Default | Description |
+|--------|------|---------|-------------|
+| `allow_read_paths` | array | `[]` | Explicit regex patterns to allow reading from (even outside workspace) |
+| `allow_write_paths` | array | `[]` | Explicit regex patterns to allow writing to (even outside workspace) |
+| `deny_read_paths` | array | `[]` | Regex patterns to explicitly block from reading (overrides workspace access) |
+| `deny_write_paths` | array | `[]` | Regex patterns to explicitly block from writing (overrides workspace access) |
+
+### Path Deny Patterns
+
+Deny patterns are useful for "hardening" a workspace. For example, to prevent an agent from manually tampering with its own skill configuration (the `skills/` directory), you can apply global block rules.
+
+**Blocking the skills directory:**
+
+```json
+{
+  "tools": {
+    "deny_read_paths": ["^skills(/.*)?$"],
+    "deny_write_paths": ["^skills(/.*)?$"]
+  }
+}
+```
+
+> **Note:** Deny patterns apply to the relative path within the workspace (when restricted) or the absolute path (when unrestricted). They take precedence over workspace access and whitelist patterns.
+
 ## Web Tools
 
 Web tools are used for web search and fetching.
diff --git a/pkg/agent/instance.go b/pkg/agent/instance.go
index 73d90dac5..f4c9a27ed 100644
--- a/pkg/agent/instance.go
+++ b/pkg/agent/instance.go
@@ -73,6 +73,8 @@ func NewAgentInstance(
 	// Compile path whitelist patterns from config.
 	allowReadPaths := buildAllowReadPatterns(cfg)
 	allowWritePaths := compilePatterns(cfg.Tools.AllowWritePaths)
+	denyReadPaths := compilePatterns(cfg.Tools.DenyReadPaths)
+	denyWritePaths := compilePatterns(cfg.Tools.DenyWritePaths)
 
 	toolsRegistry := tools.NewToolRegistry()
 
@@ -80,16 +82,16 @@ func NewAgentInstance(
 		maxReadFileSize := cfg.Tools.ReadFile.MaxReadFileSize
 		switch cfg.Tools.ReadFile.EffectiveMode() {
 		case config.ReadFileModeLines:
-			toolsRegistry.Register(tools.NewReadFileLinesTool(workspace, readRestrict, maxReadFileSize, allowReadPaths))
+			toolsRegistry.Register(tools.NewReadFileLinesTool(workspace, readRestrict, maxReadFileSize, allowReadPaths, denyReadPaths))
 		default:
-			toolsRegistry.Register(tools.NewReadFileBytesTool(workspace, readRestrict, maxReadFileSize, allowReadPaths))
+			toolsRegistry.Register(tools.NewReadFileBytesTool(workspace, readRestrict, maxReadFileSize, allowReadPaths, denyReadPaths))
 		}
 	}
 	if cfg.Tools.IsToolEnabled("write_file") {
-		toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict, allowWritePaths))
+		toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict, allowWritePaths, denyWritePaths))
 	}
 	if cfg.Tools.IsToolEnabled("list_dir") {
-		toolsRegistry.Register(tools.NewListDirTool(workspace, readRestrict, allowReadPaths))
+		toolsRegistry.Register(tools.NewListDirTool(workspace, readRestrict, allowReadPaths, denyReadPaths))
 	}
 	if cfg.Tools.IsToolEnabled("exec") {
 		execTool, err := tools.NewExecToolWithConfig(workspace, restrict, cfg, allowReadPaths)
@@ -102,10 +104,10 @@ func NewAgentInstance(
 	}
 
 	if cfg.Tools.IsToolEnabled("edit_file") {
-		toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict, allowWritePaths))
+		toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict, allowWritePaths, denyWritePaths))
 	}
 	if cfg.Tools.IsToolEnabled("append_file") {
-		toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict, allowWritePaths))
+		toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict, allowWritePaths, denyWritePaths))
 	}
 
 	// Use main agent workspace (no isolation) for sessions so that session history
diff --git a/pkg/agent/instance_test.go b/pkg/agent/instance_test.go
index 93649f8ec..209477a50 100644
--- a/pkg/agent/instance_test.go
+++ b/pkg/agent/instance_test.go
@@ -190,7 +190,7 @@ func TestNewAgentInstance_PreservesDistinctLimiterIdentityForSharedResolvedModel
 		},
 	}
 
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{})
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{}, "")
 	if len(agent.Candidates) != 2 {
 		t.Fatalf("len(Candidates) = %d, want 2", len(agent.Candidates))
 	}
@@ -319,7 +319,7 @@ func TestNewAgentInstance_ReadFileModeSelectsSchema(t *testing.T) {
 		},
 	}
 
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{})
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{}, "")
 	readTool, ok := agent.Tools.Get("read_file")
 	if !ok {
 		t.Fatal("read_file tool not registered")
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index 864e5ecc2..b01038a8d 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -178,6 +178,7 @@ func registerSharedTools(
 	provider providers.LLMProvider,
 ) {
 	allowReadPaths := buildAllowReadPatterns(cfg)
+	denyReadPaths := compilePatterns(cfg.Tools.DenyReadPaths)
 	var ttsProvider tts.TTSProvider
 	if cfg.Tools.IsToolEnabled("send_tts") {
 		ttsProvider = tts.DetectTTS(cfg)
@@ -296,14 +297,15 @@ func registerSharedTools(
 				agent.Workspace,
 				cfg.Agents.Defaults.RestrictToWorkspace,
 				cfg.Agents.Defaults.GetMaxMediaSize(),
-				nil,
+				al.mediaStore,
 				allowReadPaths,
+				denyReadPaths,
 			)
 			agent.Tools.Register(sendFileTool)
 		}
 
 		if ttsProvider != nil {
-			agent.Tools.Register(tools.NewSendTTSTool(ttsProvider, nil))
+			agent.Tools.Register(tools.NewSendTTSTool(ttsProvider, al.mediaStore))
 		}
 
 		if cfg.Tools.IsToolEnabled("load_image") {
@@ -467,6 +469,9 @@ func registerSharedTools(
 		} else if (spawnEnabled || spawnStatusEnabled) && !cfg.Tools.IsToolEnabled("subagent") {
 			logger.WarnCF("agent", "spawn/spawn_status tools require subagent to be enabled", nil)
 		}
+		// Register MCP and discovery tools to this agent
+		al.RegisterMCPToolsToAgent(agentID, agent)
+
 		// Apply global tools whitelist
 		agent.Tools.Filter(cfg.Tools.Whitelist, cfg.Tools.WhitelistEnabled)
 	}
@@ -1144,6 +1149,12 @@ func (al *AgentLoop) GetConfig() *config.Config {
 }
 
 // SetMediaStore injects a MediaStore for media lifecycle management.
+func (al *AgentLoop) GetMediaStore() media.MediaStore {
+	al.mu.RLock()
+	defer al.mu.RUnlock()
+	return al.mediaStore
+}
+
 func (al *AgentLoop) SetMediaStore(s media.MediaStore) {
 	al.mediaStore = s
 
diff --git a/pkg/agent/loop_mcp.go b/pkg/agent/loop_mcp.go
index 39e3b4d60..519b271ae 100644
--- a/pkg/agent/loop_mcp.go
+++ b/pkg/agent/loop_mcp.go
@@ -8,7 +8,6 @@ package agent
 
 import (
 	"context"
-	"fmt"
 	"sync"
 
 	"github.com/sipeed/picoclaw/pkg/config"
@@ -57,6 +56,12 @@ func (r *mcpRuntime) hasManager() bool {
 	return r.manager != nil
 }
 
+func (r *mcpRuntime) getManager() *mcp.Manager {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.manager
+}
+
 // ensureMCPInitialized loads MCP servers/tools once so both Run() and direct
 // agent mode share the same initialization path.
 func (al *AgentLoop) EnsureMCPInitialized(ctx context.Context) error {
@@ -103,112 +108,102 @@ func (al *AgentLoop) EnsureMCPInitialized(ctx context.Context) error {
 			return
 		}
 
-		// Register MCP tools for all agents
-		servers := mcpManager.GetServers()
-		uniqueTools := 0
-		totalRegistrations := 0
-		agentIDs := al.registry.ListAgentIDs()
-		agentCount := len(agentIDs)
-
-		for serverName, conn := range servers {
-			uniqueTools += len(conn.Tools)
-
-			// Determine whether this server's tools should be deferred (hidden).
-			// Per-server "deferred" field takes precedence over the global Discovery.Enabled.
-			serverCfg := al.cfg.Tools.MCP.Servers[serverName]
-			registerAsHidden := serverIsDeferred(al.cfg.Tools.MCP.Discovery.Enabled, serverCfg)
-
-			for _, tool := range conn.Tools {
-				for _, agentID := range agentIDs {
-					agent, ok := al.registry.GetAgent(agentID)
-					if !ok {
-						continue
-					}
-
-					mcpTool := tools.NewMCPTool(mcpManager, serverName, tool)
-					mcpTool.SetWorkspace(agent.Workspace)
-					mcpTool.SetMaxInlineTextRunes(al.cfg.Tools.MCP.GetMaxInlineTextChars())
-
-					if registerAsHidden {
-						agent.Tools.RegisterHidden(mcpTool)
-					} else {
-						agent.Tools.Register(mcpTool)
-					}
-
-					totalRegistrations++
-					logger.DebugCF("agent", "Registered MCP tool",
-						map[string]any{
-							"agent_id": agentID,
-							"server":   serverName,
-							"tool":     tool.Name,
-							"name":     mcpTool.Name(),
-							"deferred": registerAsHidden,
-						})
-				}
-			}
-		}
-		logger.InfoCF("agent", "MCP tools registered successfully",
-			map[string]any{
-				"server_count":        len(servers),
-				"unique_tools":        uniqueTools,
-				"total_registrations": totalRegistrations,
-				"agent_count":         agentCount,
-			})
-
-		// Initializes Discovery Tools only if enabled by configuration
-		if al.cfg.Tools.MCP.Enabled && al.cfg.Tools.MCP.Discovery.Enabled {
-			useBM25 := al.cfg.Tools.MCP.Discovery.UseBM25
-			useRegex := al.cfg.Tools.MCP.Discovery.UseRegex
-
-			// Fail fast: If discovery is enabled but no search method is turned on
-			if !useBM25 && !useRegex {
-				al.mcp.setInitErr(fmt.Errorf(
-					"tool discovery is enabled but neither 'use_bm25' nor 'use_regex' is set to true in the configuration",
-				))
-				if closeErr := mcpManager.Close(); closeErr != nil {
-					logger.ErrorCF("agent", "Failed to close MCP manager",
-						map[string]any{
-							"error": closeErr.Error(),
-						})
-				}
-				return
-			}
-
-			ttl := al.cfg.Tools.MCP.Discovery.TTL
-			if ttl <= 0 {
-				ttl = 5 // Default value
-			}
-
-			maxSearchResults := al.cfg.Tools.MCP.Discovery.MaxSearchResults
-			if maxSearchResults <= 0 {
-				maxSearchResults = 5 // Default value
-			}
-
-			logger.InfoCF("agent", "Initializing tool discovery", map[string]any{
-				"bm25": useBM25, "regex": useRegex, "ttl": ttl, "max_results": maxSearchResults,
-			})
-
-			for _, agentID := range agentIDs {
-				agent, ok := al.registry.GetAgent(agentID)
-				if !ok {
-					continue
-				}
-
-				if useRegex {
-					agent.Tools.Register(tools.NewRegexSearchTool(agent.Tools, ttl, maxSearchResults))
-				}
-				if useBM25 {
-					agent.Tools.Register(tools.NewBM25SearchTool(agent.Tools, ttl, maxSearchResults))
-				}
-			}
-		}
-
 		al.mcp.setManager(mcpManager)
+
+		// Register MCP and discovery tools for all currently known agents
+		agentIDs := al.registry.ListAgentIDs()
+		for _, agentID := range agentIDs {
+			agent, ok := al.registry.GetAgent(agentID)
+			if !ok {
+				continue
+			}
+			al.RegisterMCPToolsToAgent(agentID, agent)
+		}
+
+		logger.InfoCF("agent", "MCP initialization complete",
+			map[string]any{
+				"server_count": len(mcpManager.GetServers()),
+				"agent_count":  len(agentIDs),
+			})
 	})
 
 	return al.mcp.getInitErr()
 }
 
+// RegisterMCPToolsToAgent registers all currently active MCP tools and discovery tools to the given agent instance.
+func (al *AgentLoop) RegisterMCPToolsToAgent(agentID string, agent *AgentInstance) {
+	if !al.cfg.Tools.MCP.Enabled {
+		return
+	}
+
+	mcpManager := al.mcp.getManager()
+	if mcpManager == nil {
+		return
+	}
+
+	// 1. Register MCP server tools
+	servers := mcpManager.GetServers()
+	uniqueTools := 0
+	totalRegistrations := 0
+
+	for serverName, conn := range servers {
+		uniqueTools += len(conn.Tools)
+
+		serverCfg := al.cfg.Tools.MCP.Servers[serverName]
+		registerAsHidden := serverIsDeferred(al.cfg.Tools.MCP.Discovery.Enabled, serverCfg)
+
+		for _, tool := range conn.Tools {
+			mcpTool := tools.NewMCPTool(mcpManager, serverName, tool)
+			mcpTool.SetWorkspace(agent.Workspace)
+			mcpTool.SetMaxInlineTextRunes(al.cfg.Tools.MCP.GetMaxInlineTextChars())
+
+			if registerAsHidden {
+				agent.Tools.RegisterHidden(mcpTool)
+			} else {
+				agent.Tools.Register(mcpTool)
+			}
+			totalRegistrations++
+		}
+	}
+
+	if totalRegistrations > 0 {
+		logger.DebugCF("agent", "Registered MCP tools to agent",
+			map[string]any{
+				"agent_id":     agentID,
+				"server_count": len(servers),
+				"tool_count":   totalRegistrations,
+			})
+	}
+
+	// 2. Initializes Discovery Tools only if enabled by configuration
+	if al.cfg.Tools.MCP.Discovery.Enabled {
+		useBM25 := al.cfg.Tools.MCP.Discovery.UseBM25
+		useRegex := al.cfg.Tools.MCP.Discovery.UseRegex
+
+		if useBM25 || useRegex {
+			ttl := al.cfg.Tools.MCP.Discovery.TTL
+			if ttl <= 0 {
+				ttl = 5
+			}
+			maxSearchResults := al.cfg.Tools.MCP.Discovery.MaxSearchResults
+			if maxSearchResults <= 0 {
+				maxSearchResults = 5
+			}
+
+			if useRegex {
+				agent.Tools.Register(tools.NewRegexSearchTool(agent.Tools, ttl, maxSearchResults))
+			}
+			if useBM25 {
+				agent.Tools.Register(tools.NewBM25SearchTool(agent.Tools, ttl, maxSearchResults))
+			}
+
+			logger.DebugCF("agent", "Initialized tool discovery for agent", map[string]any{
+				"agent_id": agentID, "bm25": useBM25, "regex": useRegex,
+			})
+		}
+	}
+}
+
 // serverIsDeferred reports whether an MCP server's tools should be registered
 // as hidden (deferred/discovery mode).
 //
diff --git a/pkg/agent/multiuser_mcp_test.go b/pkg/agent/multiuser_mcp_test.go
new file mode 100644
index 000000000..0358d68bd
--- /dev/null
+++ b/pkg/agent/multiuser_mcp_test.go
@@ -0,0 +1,55 @@
+package agent
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	mcp_pkg "github.com/sipeed/picoclaw/pkg/mcp"
+)
+
+func TestMultiUserMCPPropagation(t *testing.T) {
+	cfg := &config.Config{}
+	cfg.Agents.Defaults.Workspace = t.TempDir()
+	cfg.Tools.MCP.Enabled = true
+	cfg.Tools.MCP.Servers = map[string]config.MCPServerConfig{
+		"test-server": {Enabled: true},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &mockProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	// Mock initialized MCP manager
+	mcpManager := mcp_pkg.NewManager()
+	al.mcp.setManager(mcpManager)
+
+	// 1. Create a transient agent instance
+	agent := NewAgentInstance(&config.AgentConfig{ID: "test"}, &cfg.Agents.Defaults, cfg, provider, "user-123")
+	require.NotNil(t, agent)
+
+	// 2. Register tools initially (should be nothing)
+	al.RegisterMCPToolsToAgent("test", agent)
+
+	// Verify no MCP tools yet
+	_, ok := agent.Tools.Get("mcp_test_tool")
+	assert.False(t, ok)
+
+	// 3. Test Discovery tools registration
+	cfg.Tools.MCP.Discovery.Enabled = true
+	cfg.Tools.MCP.Discovery.UseRegex = true
+
+	t.Logf("Config before registration: MCP.Enabled=%v, Discovery.Enabled=%v, UseRegex=%v",
+		cfg.Tools.MCP.Enabled, cfg.Tools.MCP.Discovery.Enabled, cfg.Tools.MCP.Discovery.UseRegex)
+
+	// Call registration again - it should now add the discovery tool
+	al.RegisterMCPToolsToAgent("test", agent)
+
+	t.Logf("Registered tools: %v", agent.Tools.List())
+
+	_, ok = agent.Tools.Get("tool_search_tool_regex")
+	assert.True(t, ok, "Discovery tool (tool_search_tool_regex) should be registered after enabling it")
+}
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 2839b605a..d4ddb9354 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -640,8 +640,8 @@ type ModelConfig struct {
 func (c *ModelConfig) UnmarshalJSON(data []byte) error {
 	type Alias ModelConfig
 	aux := &struct {
-		APIKey  string   `json:"api_key"`
-		APIKeys []string `json:"api_keys"`
+		APIKey  string              `json:"api_key"`
+		APIKeys FlexibleStringSlice `json:"api_keys"`
 		*Alias
 	}{
 		Alias: (*Alias)(c),
@@ -651,7 +651,7 @@ func (c *ModelConfig) UnmarshalJSON(data []byte) error {
 		return err
 	}
 
-	c.APIKeys = toSecureStrings(mergeAPIKeys(aux.APIKey, aux.APIKeys))
+	c.APIKeys = toSecureStrings(mergeAPIKeys(aux.APIKey, []string(aux.APIKeys)))
 	return nil
 }
 
@@ -687,8 +687,6 @@ func (c *ModelConfig) SetAPIKey(value string) {
 	}
 }
 
-
-
 type ToolDiscoveryConfig struct {
 	Enabled          bool `json:"enabled"            env:"PICOCLAW_TOOLS_DISCOVERY_ENABLED"`
 	TTL              int  `json:"ttl"                env:"PICOCLAW_TOOLS_DISCOVERY_TTL"`
@@ -843,8 +841,8 @@ type SkillsToolsConfig struct {
 	Github                SkillsGithubConfig     `yaml:"github,omitempty"                                     json:"github"`
 	MaxConcurrentSearches int                    `yaml:"-"                                                    json:"max_concurrent_searches" env:"PICOCLAW_TOOLS_SKILLS_MAX_CONCURRENT_SEARCHES"`
 	SearchCache           SearchCacheConfig      `yaml:"-"                                                    json:"search_cache"`
-	Whitelist             FlexibleStringSlice    `json:"whitelist,omitempty"                                  env:"PICOCLAW_TOOLS_SKILLS_WHITELIST"`
-	WhitelistEnabled      bool                   `json:"whitelist_enabled,omitempty"                          env:"PICOCLAW_TOOLS_SKILLS_WHITELIST_ENABLED"`
+	Whitelist             FlexibleStringSlice    `json:"whitelist,omitempty"         yaml:"-"                 env:"PICOCLAW_TOOLS_SKILLS_WHITELIST"`
+	WhitelistEnabled      bool                   `json:"whitelist_enabled,omitempty" yaml:"-"                 env:"PICOCLAW_TOOLS_SKILLS_WHITELIST_ENABLED"`
 }
 
 type MediaCleanupConfig struct {
@@ -878,6 +876,8 @@ func (c ReadFileToolConfig) EffectiveMode() string {
 type ToolsConfig struct {
 	AllowReadPaths  []string `json:"allow_read_paths"  yaml:"-" env:"PICOCLAW_TOOLS_ALLOW_READ_PATHS"`
 	AllowWritePaths []string `json:"allow_write_paths" yaml:"-" env:"PICOCLAW_TOOLS_ALLOW_WRITE_PATHS"`
+	DenyReadPaths   []string `json:"deny_read_paths"   yaml:"-" env:"PICOCLAW_TOOLS_DENY_READ_PATHS"`
+	DenyWritePaths  []string `json:"deny_write_paths"  yaml:"-" env:"PICOCLAW_TOOLS_DENY_WRITE_PATHS"`
 	// FilterSensitiveData controls whether to filter sensitive values (API keys,
 	// tokens, secrets) from tool results before sending to the LLM.
 	// Default: true (enabled)
@@ -885,31 +885,31 @@ type ToolsConfig struct {
 	// FilterMinLength is the minimum content length required for filtering.
 	// Content shorter than this will be returned unchanged for performance.
 	// Default: 8
-	FilterMinLength int                `json:"filter_min_length" yaml:"-"                env:"PICOCLAW_TOOLS_FILTER_MIN_LENGTH"`
-	Web             WebToolsConfig     `json:"web"               yaml:"web,omitempty"`
-	Cron            CronToolsConfig    `json:"cron"              yaml:"-"`
-	Exec            ExecConfig         `json:"exec"              yaml:"-"`
-	Skills          SkillsToolsConfig  `json:"skills"            yaml:"skills,omitempty"`
-	MediaCleanup    MediaCleanupConfig `json:"media_cleanup"     yaml:"-"`
+	FilterMinLength  int                 `json:"filter_min_length" yaml:"-"                env:"PICOCLAW_TOOLS_FILTER_MIN_LENGTH"`
+	Web              WebToolsConfig      `json:"web"               yaml:"web,omitempty"`
+	Cron             CronToolsConfig     `json:"cron"              yaml:"-"`
+	Exec             ExecConfig          `json:"exec"              yaml:"-"`
+	Skills           SkillsToolsConfig   `json:"skills"            yaml:"skills,omitempty"`
+	MediaCleanup     MediaCleanupConfig  `json:"media_cleanup"     yaml:"-"`
 	Whitelist        FlexibleStringSlice `json:"whitelist,omitempty"         yaml:"-" env:"PICOCLAW_TOOLS_WHITELIST"`
 	WhitelistEnabled bool                `json:"whitelist_enabled,omitempty" yaml:"-" env:"PICOCLAW_TOOLS_WHITELIST_ENABLED"`
-	MCP             MCPConfig          `json:"mcp"               yaml:"-"`
-	AppendFile      ToolConfig         `json:"append_file"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_APPEND_FILE_"`
-	EditFile        ToolConfig         `json:"edit_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_EDIT_FILE_"`
-	FindSkills      ToolConfig         `json:"find_skills"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_FIND_SKILLS_"`
-	I2C             ToolConfig         `json:"i2c"               yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_I2C_"`
-	InstallSkill    ToolConfig         `json:"install_skill"     yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_INSTALL_SKILL_"`
-	ListDir         ToolConfig         `json:"list_dir"          yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_LIST_DIR_"`
-	Message         ToolConfig         `json:"message"           yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
-	ReadFile        ReadFileToolConfig `json:"read_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
-	SendFile        ToolConfig         `json:"send_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SEND_FILE_"`
-	SendTTS         ToolConfig         `json:"send_tts"          yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SEND_TTS_"`
-	Spawn           ToolConfig         `json:"spawn"             yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SPAWN_"`
-	SpawnStatus     ToolConfig         `json:"spawn_status"      yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SPAWN_STATUS_"`
-	SPI             ToolConfig         `json:"spi"               yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SPI_"`
-	Subagent        ToolConfig         `json:"subagent"          yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SUBAGENT_"`
-	WebFetch        ToolConfig         `json:"web_fetch"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_WEB_FETCH_"`
-	WriteFile       ToolConfig         `json:"write_file"        yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_WRITE_FILE_"`
+	MCP              MCPConfig           `json:"mcp"               yaml:"-"`
+	AppendFile       ToolConfig          `json:"append_file"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_APPEND_FILE_"`
+	EditFile         ToolConfig          `json:"edit_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_EDIT_FILE_"`
+	FindSkills       ToolConfig          `json:"find_skills"       yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_FIND_SKILLS_"`
+	I2C              ToolConfig          `json:"i2c"               yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_I2C_"`
+	InstallSkill     ToolConfig          `json:"install_skill"     yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_INSTALL_SKILL_"`
+	ListDir          ToolConfig          `json:"list_dir"          yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_LIST_DIR_"`
+	Message          ToolConfig          `json:"message"           yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
+	ReadFile         ReadFileToolConfig  `json:"read_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
+	SendFile         ToolConfig          `json:"send_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SEND_FILE_"`
+	SendTTS          ToolConfig          `json:"send_tts"          yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SEND_TTS_"`
+	Spawn            ToolConfig          `json:"spawn"             yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SPAWN_"`
+	SpawnStatus      ToolConfig          `json:"spawn_status"      yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SPAWN_STATUS_"`
+	SPI              ToolConfig          `json:"spi"               yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SPI_"`
+	Subagent         ToolConfig          `json:"subagent"          yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SUBAGENT_"`
+	WebFetch         ToolConfig          `json:"web_fetch"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_WEB_FETCH_"`
+	WriteFile        ToolConfig          `json:"write_file"        yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_WRITE_FILE_"`
 }
 
 // IsFilterSensitiveDataEnabled returns true if sensitive data filtering is enabled
diff --git a/pkg/config/config_old.go b/pkg/config/config_old.go
index 150275aac..f120d56d3 100644
--- a/pkg/config/config_old.go
+++ b/pkg/config/config_old.go
@@ -832,9 +832,12 @@ type braveConfigV0 struct {
 }
 
 func toSecureStrings(keys []string) SecureStrings {
-	apikeys := make(SecureStrings, len(keys))
-	for i, key := range keys {
-		apikeys[i] = NewSecureString(key)
+	var apikeys SecureStrings
+	for _, key := range keys {
+		if key == "[NOT_HERE]" {
+			continue
+		}
+		apikeys = append(apikeys, NewSecureString(key))
 	}
 	return apikeys
 }
diff --git a/pkg/config/config_struct.go b/pkg/config/config_struct.go
index 0b8dd85c8..ac2632000 100644
--- a/pkg/config/config_struct.go
+++ b/pkg/config/config_struct.go
@@ -144,13 +144,19 @@ func (s *SecureStrings) UnmarshalJSON(value []byte) error {
 	if string(value) == notHere {
 		return nil
 	}
+	// Try []string first
 	var v []*SecureString
-	err := json.Unmarshal(value, &v)
-	if err != nil {
-		return err
+	if err := json.Unmarshal(value, &v); err == nil {
+		*s = v
+		return nil
 	}
-	*s = v
-	return nil
+	// Fallback to single string
+	var single *SecureString
+	if err := json.Unmarshal(value, &single); err == nil {
+		*s = []*SecureString{single}
+		return nil
+	}
+	return json.Unmarshal(value, &v) // Return original error
 }
 
 // SecureString the string value that can be decrypted or resolved
diff --git a/pkg/config/gateway.go b/pkg/config/gateway.go
index 30e6f4204..06df7e5bb 100644
--- a/pkg/config/gateway.go
+++ b/pkg/config/gateway.go
@@ -18,7 +18,6 @@ type GatewayConfig struct {
 	LogLevel    string `json:"log_level,omitempty" env:"PICOCLAW_LOG_LEVEL"`
 }
 
-
 func canonicalGatewayLogLevel(level logger.LogLevel) string {
 	switch level {
 	case logger.DEBUG:
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
index 0f20f79b4..397091d30 100644
--- a/pkg/gateway/gateway.go
+++ b/pkg/gateway/gateway.go
@@ -111,28 +111,39 @@ func (p *startupBlockedProvider) GetDefaultModel() string {
 
 // Run starts the gateway runtime using the configuration loaded from configPath.
 func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error {
+	fmt.Printf("🚀 PicoClaw Gateway starting...\n")
+	fmt.Printf("📂 Home Path: %s\n", homePath)
+	fmt.Printf("📄 Config Path: %s\n", configPath)
+
 	panicPath := filepath.Join(homePath, logPath, panicFile)
+	fmt.Printf("🔧 Initializing panic log: %s\n", panicPath)
 	panicFunc, err := logger.InitPanic(panicPath)
 	if err != nil {
-		return fmt.Errorf("error initializing panic log: %w", err)
+		fmt.Printf("⚠️  Warning: error initializing panic log (continuing): %v\n", err)
+	} else if panicFunc != nil {
+		defer panicFunc()
+		fmt.Println("✓ Panic log initialized")
 	}
-	defer panicFunc()
 
-	if err = logger.EnableFileLogging(filepath.Join(homePath, logPath, logFile)); err != nil {
-		logger.Fatal(fmt.Sprintf("error enabling file logging: %v", err))
+	logFilePath := filepath.Join(homePath, logPath, logFile)
+	fmt.Printf("🔧 Enabling file logging: %s\n", logFilePath)
+	if err = logger.EnableFileLogging(logFilePath); err != nil {
+		fmt.Printf("⚠️  Warning: error initializing file logging (continuing): %v\n", err)
+	} else {
+		defer logger.DisableFileLogging()
+		fmt.Println("✓ File logging enabled")
+	}
+
+	fmt.Println("🔍 Loading configuration...")
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		return fmt.Errorf("error loading config: %w", err)
 	}
-	defer logger.DisableFileLogging()
 
 	if debug {
 		logger.SetLevel(logger.DEBUG)
 	} else {
-		logger.SetLevelFromString(config.ResolveGatewayLogLevel(configPath))
-	}
-
-<<<<<<< HEAD
-	cfg, err := config.LoadConfig(configPath)
-	if err != nil {
-		logger.Fatalf("error loading config: %v", err)
+		logger.SetLevelFromString(cfg.Gateway.LogLevel)
 	}
 
 	if err = preCheckConfig(cfg); err != nil {
@@ -156,9 +167,7 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 	}
 	defer pid.RemovePidFile(homePath)
 
-=======
 	fmt.Printf("🔍 Creating startup provider for model: %s (allow empty: %v)\n", cfg.Agents.Defaults.GetModelName(), allowEmptyStartup)
->>>>>>> 46dc6e5 (Synchronize hardening: added onboard purge, non-interactive mode, and diagnostic startup logs)
 	provider, modelID, err := createStartupProvider(cfg, allowEmptyStartup)
 	if err != nil {
 		fmt.Printf("❌ Error creating provider: %v\n", err)
@@ -194,7 +203,6 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 		return err
 	}
 
-
 	// Setup manual reload channel for /reload endpoint
 	manualReloadChan := make(chan struct{}, 1)
 	runningServices.manualReloadChan = manualReloadChan
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 2ff2dae6e..736479eda 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -13,6 +13,11 @@ import (
 	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
+// Mux defines the interface required for registering health handlers.
+type Mux interface {
+	HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
+}
+
 // ChatRequest is the JSON body for POST /chat.
 type ChatRequest struct {
 	Message   string `json:"message"`
@@ -36,7 +41,6 @@ type chatStatus struct {
 }
 
 type Server struct {
-
 	server        *http.Server
 	mu            sync.RWMutex
 	ready         bool
@@ -50,7 +54,6 @@ type Server struct {
 	chatResultsMu sync.RWMutex
 }
 
-
 type Check struct {
 	Name      string    `json:"name"`
 	Status    string    `json:"status"`
@@ -79,7 +82,6 @@ func NewServer(host string, port int, token string) *Server {
 	mux.HandleFunc("/ready", s.readyHandler)
 	mux.HandleFunc("/reload", s.reloadHandler)
 	mux.HandleFunc("/chat", s.chatHandler)
-	mux.HandleFunc("/cgat", s.chatHandler)
 
 	// Start task cleanup goroutine
 	go s.taskCleanupLoop()
@@ -271,16 +273,11 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
 
 // RegisterOnMux registers /health, /ready, /reload and /chat handlers onto the
 // given mux. This allows the health endpoints to be served by a shared HTTP server.
-func (s *Server) RegisterOnMux(mux *http.ServeMux) {
+func (s *Server) RegisterOnMux(mux Mux) {
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
 	mux.HandleFunc("/reload", s.reloadHandler)
 	mux.HandleFunc("/chat", s.chatHandler)
-	mux.HandleFunc("/cgat", s.chatHandler)
-	mux.HandleFunc("/v1/chat/completions", func(w http.ResponseWriter, r *http.Request) {
-		logger.Error("GATEWAY IS HITTING ITSELF FOR LLM CALLS!")
-		http.Error(w, "GATEWAY LOOP DETECTION", http.StatusLoopDetected)
-	})
 }
 
 // chatHandler handles POST /chat (initiate async) and GET /chat (poll for result).
@@ -346,6 +343,8 @@ func (s *Server) handlePostChat(w http.ResponseWriter, r *http.Request) {
 		// These are ordered by specificity/reliability
 		headers := []string{
 			"X-PicoClaw-Chat-ID",
+			"X-MS-CONVERSATION-ID", // Teams Conversation ID
+			"X-MS-TENANT-ID",       // Teams Tenant ID
 			"X-User-ID",
 			"X-Session-ID",
 			"X-MS-CLIENT-PRINCIPAL-ID",   // Azure App Service / Container Apps (EasyAuth)
diff --git a/pkg/logger/panic.go b/pkg/logger/panic.go
index 0a9125dda..f8df39268 100644
--- a/pkg/logger/panic.go
+++ b/pkg/logger/panic.go
@@ -17,7 +17,7 @@ func InitPanic(filePath string) (func(), error) {
 	}
 	writer := initPanicFile(filePath)
 	if writer == nil {
-		return nil, fmt.Errorf("failed to create log file: %s", filePath)
+		return nil, nil
 	}
 	if panicWriter != nil {
 		_ = panicWriter.Close()
diff --git a/pkg/logger/panic_unix.go b/pkg/logger/panic_unix.go
index 48f393b45..1a3745d33 100644
--- a/pkg/logger/panic_unix.go
+++ b/pkg/logger/panic_unix.go
@@ -13,10 +13,13 @@ import (
 func initPanicFile(panicFile string) io.WriteCloser {
 	file, err := os.OpenFile(panicFile, os.O_WRONLY|os.O_CREATE|os.O_APPEND|os.O_SYNC, 0o600)
 	if err != nil {
-		panic(fmt.Sprintf("error in open panic: %v", err))
+		fmt.Fprintf(os.Stdout, "Failed to open panic log file %s: %v\n", panicFile, err)
+		return nil
 	}
 	if err = unix.Dup2(int(file.Fd()), int(os.Stderr.Fd())); err != nil {
-		panic(fmt.Sprintf("error in syscall.Dup2: %v", err))
+		fmt.Fprintf(os.Stdout, "Failed to dup2 panic log: %v\n", err)
+		file.Close()
+		return nil
 	}
 	return file
 }
diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index 653d8732f..ddad48a94 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -217,7 +217,7 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 		}
 		return provider, modelID, nil
 
-	case "litellm", "lmstudio", "openrouter", "groq", "zhipu", "gemini", "nvidia", "venice",
+	case "litellm", "lmstudio", "openrouter", "groq", "zhipu", "gemini", "venice",
 		"ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
 		"vivgrid", "volcengine", "vllm", "qwen", "qwen-intl", "qwen-international", "dashscope-intl",
 		"qwen-us", "dashscope-us", "mistral", "avian", "longcat", "modelscope", "novita",
@@ -250,6 +250,7 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 			apiBase,
 			cfg.Proxy,
 			cfg.MaxTokensField,
+			userAgent,
 			cfg.RequestTimeout,
 			cfg.ExtraBody,
 		)
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index 6df03c606..0e197d754 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -51,12 +51,16 @@ func NewAzureAIProvider(apiKey, apiBase, proxy string, requestTimeoutSeconds int
 			apiKey,
 			apiBase,
 			proxy,
-			openai_compat.WithAzureHeaders(),
+			openai_compat.WithAzureHeaders(true),
 			openai_compat.WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
 		),
 	}
 }
 
+func (p *HTTPProvider) SetUseAzureHeaders(use bool) {
+	p.delegate.SetUseAzureHeaders(use)
+}
+
 func (p *HTTPProvider) Chat(
 	ctx context.Context,
 	messages []Message,
@@ -84,10 +88,6 @@ func (p *HTTPProvider) GetDefaultModel() string {
 	return ""
 }
 
-func (p *HTTPProvider) SetUseAzureHeaders(use bool) {
-	p.delegate.SetUseAzureHeaders(use)
-}
-
 func (p *HTTPProvider) SupportsNativeSearch() bool {
 	return p.delegate.SupportsNativeSearch()
 }
diff --git a/pkg/providers/openai_compat/provider.go b/pkg/providers/openai_compat/provider.go
index 279b518f5..02a41a344 100644
--- a/pkg/providers/openai_compat/provider.go
+++ b/pkg/providers/openai_compat/provider.go
@@ -14,7 +14,6 @@ import (
 	"sync"
 	"time"
 
-
 	"github.com/sipeed/picoclaw/pkg/providers/common"
 	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
 )
@@ -43,33 +42,30 @@ type Provider struct {
 	mu              sync.RWMutex // Protect useAzureHeaders
 }
 
-
-
 type Option func(*Provider)
 
 const defaultRequestTimeout = common.DefaultRequestTimeout
 
 var stripModelPrefixProviders = map[string]struct{}{
-	"litellm":    {},
-	"venice":     {},
-	"moonshot":   {},
-	"nvidia":     {},
-	"groq":       {},
-	"ollama":     {},
-	"deepseek":   {},
-	"google":     {},
-	"openrouter": {},
-	"zhipu":      {},
-	"mistral":    {},
-	"vivgrid":    {},
-	"minimax":    {},
+	"litellm":       {},
+	"venice":        {},
+	"moonshot":      {},
+	"nvidia":        {},
+	"groq":          {},
+	"ollama":        {},
+	"deepseek":      {},
+	"google":        {},
+	"openrouter":    {},
+	"zhipu":         {},
+	"mistral":       {},
+	"vivgrid":       {},
+	"minimax":       {},
 	"novita":        {},
 	"lmstudio":      {},
 	"azure-ai":      {},
 	"azure-foundry": {},
 }
 
-
 func WithMaxTokensField(maxTokensField string) Option {
 	return func(p *Provider) {
 		p.maxTokensField = maxTokensField
@@ -108,7 +104,6 @@ func (p *Provider) SetUseAzureHeaders(use bool) {
 	p.useAzureHeaders = use
 }
 
-
 func NewProvider(apiKey, apiBase, proxy string, opts ...Option) *Provider {
 	p := &Provider{
 		apiKey:     apiKey,
diff --git a/pkg/tools/edit.go b/pkg/tools/edit.go
index d5bebf4a2..e84481c94 100644
--- a/pkg/tools/edit.go
+++ b/pkg/tools/edit.go
@@ -16,12 +16,12 @@ type EditFileTool struct {
 }
 
 // NewEditFileTool creates a new EditFileTool with optional directory restriction.
-func NewEditFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *EditFileTool {
-	var patterns []*regexp.Regexp
-	if len(allowPaths) > 0 {
-		patterns = allowPaths[0]
+func NewEditFileTool(workspace string, restrict bool, allowPaths []*regexp.Regexp, denyPaths ...[]*regexp.Regexp) *EditFileTool {
+	var denyPatterns []*regexp.Regexp
+	if len(denyPaths) > 0 {
+		denyPatterns = denyPaths[0]
 	}
-	return &EditFileTool{fs: buildFs(workspace, restrict, patterns)}
+	return &EditFileTool{fs: buildFs(workspace, restrict, allowPaths, denyPatterns)}
 }
 
 func (t *EditFileTool) Name() string {
@@ -79,12 +79,12 @@ type AppendFileTool struct {
 	fs fileSystem
 }
 
-func NewAppendFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *AppendFileTool {
-	var patterns []*regexp.Regexp
-	if len(allowPaths) > 0 {
-		patterns = allowPaths[0]
+func NewAppendFileTool(workspace string, restrict bool, allowPaths []*regexp.Regexp, denyPaths ...[]*regexp.Regexp) *AppendFileTool {
+	var denyPatterns []*regexp.Regexp
+	if len(denyPaths) > 0 {
+		denyPatterns = denyPaths[0]
 	}
-	return &AppendFileTool{fs: buildFs(workspace, restrict, patterns)}
+	return &AppendFileTool{fs: buildFs(workspace, restrict, allowPaths, denyPatterns)}
 }
 
 func (t *AppendFileTool) Name() string {
diff --git a/pkg/tools/edit_test.go b/pkg/tools/edit_test.go
index 83a7e778c..a950a6566 100644
--- a/pkg/tools/edit_test.go
+++ b/pkg/tools/edit_test.go
@@ -16,7 +16,7 @@ func TestEditTool_EditFile_Success(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "test.txt")
 	os.WriteFile(testFile, []byte("Hello World\nThis is a test"), 0o644)
 
-	tool := NewEditFileTool(tmpDir, true)
+	tool := NewEditFileTool(tmpDir, true, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     testFile,
@@ -60,7 +60,7 @@ func TestEditTool_EditFile_NotFound(t *testing.T) {
 	tmpDir := t.TempDir()
 	testFile := filepath.Join(tmpDir, "nonexistent.txt")
 
-	tool := NewEditFileTool(tmpDir, true)
+	tool := NewEditFileTool(tmpDir, true, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     testFile,
@@ -87,7 +87,7 @@ func TestEditTool_EditFile_OldTextNotFound(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "test.txt")
 	os.WriteFile(testFile, []byte("Hello World"), 0o644)
 
-	tool := NewEditFileTool(tmpDir, true)
+	tool := NewEditFileTool(tmpDir, true, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     testFile,
@@ -114,7 +114,7 @@ func TestEditTool_EditFile_MultipleMatches(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "test.txt")
 	os.WriteFile(testFile, []byte("test test test"), 0o644)
 
-	tool := NewEditFileTool(tmpDir, true)
+	tool := NewEditFileTool(tmpDir, true, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     testFile,
@@ -142,7 +142,7 @@ func TestEditTool_EditFile_OutsideAllowedDir(t *testing.T) {
 	testFile := filepath.Join(otherDir, "test.txt")
 	os.WriteFile(testFile, []byte("content"), 0o644)
 
-	tool := NewEditFileTool(tmpDir, true) // Restrict to tmpDir
+	tool := NewEditFileTool(tmpDir, true, nil) // Restrict to tmpDir
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     testFile,
@@ -169,7 +169,7 @@ func TestEditTool_EditFile_OutsideAllowedDir(t *testing.T) {
 
 // TestEditTool_EditFile_MissingPath verifies error handling for missing path
 func TestEditTool_EditFile_MissingPath(t *testing.T) {
-	tool := NewEditFileTool("", false)
+	tool := NewEditFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"old_text": "old",
@@ -186,7 +186,7 @@ func TestEditTool_EditFile_MissingPath(t *testing.T) {
 
 // TestEditTool_EditFile_MissingOldText verifies error handling for missing old_text
 func TestEditTool_EditFile_MissingOldText(t *testing.T) {
-	tool := NewEditFileTool("", false)
+	tool := NewEditFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     "/tmp/test.txt",
@@ -203,7 +203,7 @@ func TestEditTool_EditFile_MissingOldText(t *testing.T) {
 
 // TestEditTool_EditFile_MissingNewText verifies error handling for missing new_text
 func TestEditTool_EditFile_MissingNewText(t *testing.T) {
-	tool := NewEditFileTool("", false)
+	tool := NewEditFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     "/tmp/test.txt",
@@ -224,7 +224,7 @@ func TestEditTool_AppendFile_Success(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "test.txt")
 	os.WriteFile(testFile, []byte("Initial content"), 0o644)
 
-	tool := NewAppendFileTool("", false)
+	tool := NewAppendFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":    testFile,
@@ -264,7 +264,7 @@ func TestEditTool_AppendFile_Success(t *testing.T) {
 
 // TestEditTool_AppendFile_MissingPath verifies error handling for missing path
 func TestEditTool_AppendFile_MissingPath(t *testing.T) {
-	tool := NewAppendFileTool("", false)
+	tool := NewAppendFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"content": "test",
@@ -280,7 +280,7 @@ func TestEditTool_AppendFile_MissingPath(t *testing.T) {
 
 // TestEditTool_AppendFile_MissingContent verifies error handling for missing content
 func TestEditTool_AppendFile_MissingContent(t *testing.T) {
-	tool := NewAppendFileTool("", false)
+	tool := NewAppendFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": "/tmp/test.txt",
@@ -348,7 +348,7 @@ func TestReplaceEditContent(t *testing.T) {
 // This exercises the errors.Is(err, fs.ErrNotExist) path in appendFileWithRW + rootRW.
 func TestAppendFileTool_AppendToNonExistent_Restricted(t *testing.T) {
 	workspace := t.TempDir()
-	tool := NewAppendFileTool(workspace, true)
+	tool := NewAppendFileTool(workspace, true, nil)
 	ctx := context.Background()
 
 	args := map[string]any{
@@ -378,7 +378,7 @@ func TestAppendFileTool_Restricted_Success(t *testing.T) {
 	err := os.WriteFile(filepath.Join(workspace, testFile), []byte("initial"), 0o644)
 	assert.NoError(t, err)
 
-	tool := NewAppendFileTool(workspace, true)
+	tool := NewAppendFileTool(workspace, true, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":    testFile,
@@ -402,7 +402,7 @@ func TestEditFileTool_Restricted_InPlaceEdit(t *testing.T) {
 	err := os.WriteFile(filepath.Join(workspace, testFile), []byte("Hello World"), 0o644)
 	assert.NoError(t, err)
 
-	tool := NewEditFileTool(workspace, true)
+	tool := NewEditFileTool(workspace, true, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     testFile,
@@ -423,7 +423,7 @@ func TestEditFileTool_Restricted_InPlaceEdit(t *testing.T) {
 // error message when the target file does not exist.
 func TestEditFileTool_Restricted_FileNotFound(t *testing.T) {
 	workspace := t.TempDir()
-	tool := NewEditFileTool(workspace, true)
+	tool := NewEditFileTool(workspace, true, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":     "no_such_file.txt",
diff --git a/pkg/tools/filesystem.go b/pkg/tools/filesystem.go
index 0b9a16950..84e5a6388 100644
--- a/pkg/tools/filesystem.go
+++ b/pkg/tools/filesystem.go
@@ -256,6 +256,19 @@ func isWithinWorkspace(candidate, workspace string) bool {
 	return err == nil && (rel == "." || filepath.IsLocal(rel))
 }
 
+func isDeniedPath(path string, patterns []*regexp.Regexp) bool {
+	if len(patterns) == 0 {
+		return false
+	}
+	cleaned := filepath.Clean(path)
+	for _, pattern := range patterns {
+		if pattern.MatchString(cleaned) {
+			return true
+		}
+	}
+	return false
+}
+
 type ReadFileTool struct {
 	fs      fileSystem
 	maxSize int64
@@ -270,11 +283,15 @@ func NewReadFileTool(
 	workspace string,
 	restrict bool,
 	maxReadFileSize int,
-	allowPaths ...[]*regexp.Regexp,
+	configs ...[]*regexp.Regexp,
 ) *ReadFileTool {
-	var patterns []*regexp.Regexp
-	if len(allowPaths) > 0 {
-		patterns = allowPaths[0]
+	var allowPatterns []*regexp.Regexp
+	var denyPatterns []*regexp.Regexp
+	if len(configs) > 0 {
+		allowPatterns = configs[0]
+	}
+	if len(configs) > 1 {
+		denyPatterns = configs[1]
 	}
 
 	maxSize := int64(maxReadFileSize)
@@ -283,7 +300,7 @@ func NewReadFileTool(
 	}
 
 	return &ReadFileTool{
-		fs:      buildFs(workspace, restrict, patterns),
+		fs:      buildFs(workspace, restrict, allowPatterns, denyPatterns),
 		maxSize: maxSize,
 	}
 }
@@ -292,20 +309,24 @@ func NewReadFileBytesTool(
 	workspace string,
 	restrict bool,
 	maxReadFileSize int,
-	allowPaths ...[]*regexp.Regexp,
+	configs ...[]*regexp.Regexp,
 ) *ReadFileTool {
-	return NewReadFileTool(workspace, restrict, maxReadFileSize, allowPaths...)
+	return NewReadFileTool(workspace, restrict, maxReadFileSize, configs...)
 }
 
 func NewReadFileLinesTool(
 	workspace string,
 	restrict bool,
 	maxReadFileSize int,
-	allowPaths ...[]*regexp.Regexp,
+	configs ...[]*regexp.Regexp,
 ) *ReadFileLinesTool {
-	var patterns []*regexp.Regexp
-	if len(allowPaths) > 0 {
-		patterns = allowPaths[0]
+	var allowPatterns []*regexp.Regexp
+	var denyPatterns []*regexp.Regexp
+	if len(configs) > 0 {
+		allowPatterns = configs[0]
+	}
+	if len(configs) > 1 {
+		denyPatterns = configs[1]
 	}
 
 	maxSize := int64(maxReadFileSize)
@@ -314,7 +335,7 @@ func NewReadFileLinesTool(
 	}
 
 	return &ReadFileLinesTool{
-		fs:      buildFs(workspace, restrict, patterns),
+		fs:      buildFs(workspace, restrict, allowPatterns, denyPatterns),
 		maxSize: maxSize,
 	}
 }
@@ -853,16 +874,16 @@ type WriteFileTool struct {
 	fs fileSystem
 }
 
-func NewWriteFileTool(
-	workspace string,
-	restrict bool,
-	allowPaths ...[]*regexp.Regexp,
-) *WriteFileTool {
-	var patterns []*regexp.Regexp
-	if len(allowPaths) > 0 {
-		patterns = allowPaths[0]
+func NewWriteFileTool(workspace string, restrict bool, configs ...[]*regexp.Regexp) *WriteFileTool {
+	var allowPatterns []*regexp.Regexp
+	var denyPatterns []*regexp.Regexp
+	if len(configs) > 0 {
+		allowPatterns = configs[0]
 	}
-	return &WriteFileTool{fs: buildFs(workspace, restrict, patterns)}
+	if len(configs) > 1 {
+		denyPatterns = configs[1]
+	}
+	return &WriteFileTool{fs: buildFs(workspace, restrict, allowPatterns, denyPatterns)}
 }
 
 func (t *WriteFileTool) Name() string {
@@ -927,12 +948,16 @@ type ListDirTool struct {
 	fs fileSystem
 }
 
-func NewListDirTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *ListDirTool {
-	var patterns []*regexp.Regexp
-	if len(allowPaths) > 0 {
-		patterns = allowPaths[0]
+func NewListDirTool(workspace string, restrict bool, configs ...[]*regexp.Regexp) *ListDirTool {
+	var allowPatterns []*regexp.Regexp
+	var denyPatterns []*regexp.Regexp
+	if len(configs) > 0 {
+		allowPatterns = configs[0]
 	}
-	return &ListDirTool{fs: buildFs(workspace, restrict, patterns)}
+	if len(configs) > 1 {
+		denyPatterns = configs[1]
+	}
+	return &ListDirTool{fs: buildFs(workspace, restrict, allowPatterns, denyPatterns)}
 }
 
 func (t *ListDirTool) Name() string {
@@ -991,9 +1016,14 @@ type fileSystem interface {
 }
 
 // hostFs is an unrestricted fileReadWriter that operates directly on the host filesystem.
-type hostFs struct{}
+type hostFs struct {
+	denyPatterns []*regexp.Regexp
+}
 
 func (h *hostFs) ReadFile(path string) ([]byte, error) {
+	if isDeniedPath(path, h.denyPatterns) {
+		return nil, fmt.Errorf("access denied: path is blocked by security policy")
+	}
 	content, err := os.ReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -1008,16 +1038,25 @@ func (h *hostFs) ReadFile(path string) ([]byte, error) {
 }
 
 func (h *hostFs) ReadDir(path string) ([]os.DirEntry, error) {
+	if isDeniedPath(path, h.denyPatterns) {
+		return nil, fmt.Errorf("access denied: path is blocked by security policy")
+	}
 	return os.ReadDir(path)
 }
 
 func (h *hostFs) WriteFile(path string, data []byte) error {
+	if isDeniedPath(path, h.denyPatterns) {
+		return fmt.Errorf("access denied: path is blocked by security policy")
+	}
 	// Use unified atomic write utility with explicit sync for flash storage reliability.
 	// Using 0o600 (owner read/write only) for secure default permissions.
 	return fileutil.WriteFileAtomic(path, data, 0o600)
 }
 
 func (h *hostFs) Open(path string) (fs.File, error) {
+	if isDeniedPath(path, h.denyPatterns) {
+		return nil, fmt.Errorf("access denied: path is blocked by security policy")
+	}
 	f, err := os.Open(path)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -1033,7 +1072,8 @@ func (h *hostFs) Open(path string) (fs.File, error) {
 
 // sandboxFs is a sandboxed fileSystem that operates within a strictly defined workspace using os.Root.
 type sandboxFs struct {
-	workspace string
+	workspace    string
+	denyPatterns []*regexp.Regexp
 }
 
 func (r *sandboxFs) execute(path string, fn func(root *os.Root, relPath string) error) error {
@@ -1052,6 +1092,10 @@ func (r *sandboxFs) execute(path string, fn func(root *os.Root, relPath string)
 		return err
 	}
 
+	if isDeniedPath(relPath, r.denyPatterns) {
+		return fmt.Errorf("access denied: path is blocked by security policy")
+	}
+
 	return fn(root, relPath)
 }
 
@@ -1204,13 +1248,13 @@ func (w *whitelistFs) Open(path string) (fs.File, error) {
 
 // buildFs returns the appropriate fileSystem implementation based on restriction
 // settings and optional path whitelist patterns.
-func buildFs(workspace string, restrict bool, patterns []*regexp.Regexp) fileSystem {
+func buildFs(workspace string, restrict bool, allowPatterns, denyPatterns []*regexp.Regexp) fileSystem {
 	if !restrict {
-		return &hostFs{}
+		return &hostFs{denyPatterns: denyPatterns}
 	}
-	sandbox := &sandboxFs{workspace: workspace}
-	if len(patterns) > 0 {
-		return &whitelistFs{sandbox: sandbox, patterns: patterns}
+	sandbox := &sandboxFs{workspace: workspace, denyPatterns: denyPatterns}
+	if len(allowPatterns) > 0 {
+		return &whitelistFs{sandbox: sandbox, patterns: allowPatterns}
 	}
 	return sandbox
 }
@@ -1236,3 +1280,36 @@ func getSafeRelPath(workspace, path string) (string, error) {
 
 	return rel, nil
 }
+
+// validatePathWithConfigs returns the resolved absolute path if it is allowed
+// by the given workspace, restriction setting, and path whitelist/blacklist.
+func validatePathWithConfigs(path, workspace string, restrict bool, allowPatterns, denyPatterns []*regexp.Regexp) (string, error) {
+	cleaned := filepath.Clean(path)
+	var resolved string
+
+	if !filepath.IsAbs(cleaned) {
+		resolved = filepath.Join(workspace, cleaned)
+	} else {
+		resolved = cleaned
+	}
+
+	// 1. Check blacklist first
+	if isDeniedPath(resolved, denyPatterns) {
+		return "", fmt.Errorf("access to %s is denied by policy", path)
+	}
+
+	// 2. Check whitelist (explicit allow)
+	if isAllowedPath(resolved, allowPatterns) {
+		return resolved, nil
+	}
+
+	// 3. Check workspace sandbox if restricted
+	if restrict {
+		rel, err := filepath.Rel(workspace, resolved)
+		if err != nil || !filepath.IsLocal(rel) {
+			return "", fmt.Errorf("path %s is outside workspace and not whitelisted", path)
+		}
+	}
+
+	return resolved, nil
+}
diff --git a/pkg/tools/filesystem_test.go b/pkg/tools/filesystem_test.go
index bfbc1f46e..9b2494d9c 100644
--- a/pkg/tools/filesystem_test.go
+++ b/pkg/tools/filesystem_test.go
@@ -94,7 +94,7 @@ func TestFilesystemTool_WriteFile_Success(t *testing.T) {
 	tmpDir := t.TempDir()
 	testFile := filepath.Join(tmpDir, "newfile.txt")
 
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":    testFile,
@@ -133,7 +133,7 @@ func TestFilesystemTool_WriteFile_CreateDir(t *testing.T) {
 	tmpDir := t.TempDir()
 	testFile := filepath.Join(tmpDir, "subdir", "newfile.txt")
 
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path":    testFile,
@@ -159,7 +159,7 @@ func TestFilesystemTool_WriteFile_CreateDir(t *testing.T) {
 
 // TestFilesystemTool_WriteFile_MissingPath verifies error handling for missing path
 func TestFilesystemTool_WriteFile_MissingPath(t *testing.T) {
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"content": "test",
@@ -175,7 +175,7 @@ func TestFilesystemTool_WriteFile_MissingPath(t *testing.T) {
 
 // TestFilesystemTool_WriteFile_MissingContent verifies error handling for missing content
 func TestFilesystemTool_WriteFile_MissingContent(t *testing.T) {
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": "/tmp/test.txt",
@@ -202,7 +202,7 @@ func TestFilesystemTool_WriteFile_OverwriteDefaultBlocked(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "existing.txt")
 	os.WriteFile(testFile, []byte("original"), 0o644)
 
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	result := tool.Execute(context.Background(), map[string]any{
 		"path":    testFile,
 		"content": "new content",
@@ -225,7 +225,7 @@ func TestFilesystemTool_WriteFile_OverwriteExplicitAllowed(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "existing.txt")
 	os.WriteFile(testFile, []byte("original"), 0o644)
 
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	result := tool.Execute(context.Background(), map[string]any{
 		"path":      testFile,
 		"content":   "replaced",
@@ -245,7 +245,7 @@ func TestFilesystemTool_WriteFile_NewFileNoOverwriteFlag(t *testing.T) {
 	tmpDir := t.TempDir()
 	testFile := filepath.Join(tmpDir, "newfile.txt")
 
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	result := tool.Execute(context.Background(), map[string]any{
 		"path":    testFile,
 		"content": "brand new",
@@ -265,7 +265,7 @@ func TestFilesystemTool_WriteFile_OverwriteFalseExplicitBlocked(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "existing.txt")
 	os.WriteFile(testFile, []byte("original"), 0o644)
 
-	tool := NewWriteFileTool("", false)
+	tool := NewWriteFileTool("", false, nil)
 	result := tool.Execute(context.Background(), map[string]any{
 		"path":      testFile,
 		"content":   "new content",
@@ -287,7 +287,7 @@ func TestFilesystemTool_WriteFile_OverwriteSandboxed(t *testing.T) {
 	testFile := "file.txt"
 	os.WriteFile(filepath.Join(workspace, testFile), []byte("original"), 0o644)
 
-	tool := NewWriteFileTool(workspace, true)
+	tool := NewWriteFileTool(workspace, true, nil)
 
 	// Without overwrite=true → blocked
 	result := tool.Execute(context.Background(), map[string]any{
@@ -322,7 +322,7 @@ func TestFilesystemTool_ListDir_Success(t *testing.T) {
 	os.WriteFile(filepath.Join(tmpDir, "file2.txt"), []byte("content"), 0o644)
 	os.Mkdir(filepath.Join(tmpDir, "subdir"), 0o755)
 
-	tool := NewListDirTool("", false)
+	tool := NewListDirTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": tmpDir,
@@ -347,7 +347,7 @@ func TestFilesystemTool_ListDir_Success(t *testing.T) {
 
 // TestFilesystemTool_ListDir_NotFound verifies error handling for non-existent directory
 func TestFilesystemTool_ListDir_NotFound(t *testing.T) {
-	tool := NewListDirTool("", false)
+	tool := NewListDirTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": "/nonexistent_directory_12345",
@@ -373,7 +373,7 @@ func TestFilesystemTool_ListDir_NotFound(t *testing.T) {
 
 // TestFilesystemTool_ListDir_DefaultPath verifies default to current directory
 func TestFilesystemTool_ListDir_DefaultPath(t *testing.T) {
-	tool := NewListDirTool("", false)
+	tool := NewListDirTool("", false, nil)
 	ctx := context.Background()
 	args := map[string]any{}
 
@@ -403,7 +403,7 @@ func TestFilesystemTool_ReadFile_RejectsSymlinkEscape(t *testing.T) {
 		t.Skipf("symlink not supported in this environment: %v", err)
 	}
 
-	tool := NewReadFileTool(workspace, true, MaxReadFileSize)
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize, nil)
 	result := tool.Execute(context.Background(), map[string]any{
 		"path": link,
 	})
@@ -422,7 +422,7 @@ func TestFilesystemTool_ReadFile_RejectsSymlinkEscape(t *testing.T) {
 }
 
 func TestFilesystemTool_EmptyWorkspace_AccessDenied(t *testing.T) {
-	tool := NewReadFileTool("", true, MaxReadFileSize) // restrict=true but workspace=""
+	tool := NewReadFileTool("", true, MaxReadFileSize, nil) // restrict=true but workspace=""
 
 	// Try to read a sensitive file (simulated by a temp file outside workspace)
 	tmpDir := t.TempDir()
@@ -485,7 +485,7 @@ func TestRootMkdirAll(t *testing.T) {
 
 func TestFilesystemTool_WriteFile_Restricted_CreateDir(t *testing.T) {
 	workspace := t.TempDir()
-	tool := NewWriteFileTool(workspace, true)
+	tool := NewWriteFileTool(workspace, true, nil)
 	ctx := context.Background()
 
 	testFile := "deep/nested/path/to/file.txt"
@@ -763,7 +763,7 @@ func TestReadFileTool_ChunkedReading(t *testing.T) {
 		t.Fatalf("Failed to write test file: %v", err)
 	}
 
-	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize)
+	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize, nil)
 	ctx := context.Background()
 
 	// --- Step 1: Read the first chunk (10 bytes) ---
@@ -841,7 +841,7 @@ func TestReadFileTool_OffsetBeyondEOF(t *testing.T) {
 		t.Fatalf("Failed to write test file: %v", err)
 	}
 
-	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize)
+	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize, nil)
 	ctx := context.Background()
 
 	args := map[string]any{
@@ -1236,3 +1236,66 @@ func TestReadFileLinesTool_ExactByteBudgetBoundaryIncludesPrefix(t *testing.T) {
 		t.Fatalf("expected continuation at line 2, got: %s", result.ForLLM)
 	}
 }
+
+func TestFileSystem_DenyPatterns(t *testing.T) {
+	tmpDir := t.TempDir()
+	ctx := context.Background()
+
+	// Create a simulated skills directory
+	skillsDir := filepath.Join(tmpDir, "skills", "secret-skill")
+	os.MkdirAll(skillsDir, 0o755)
+	skillFile := filepath.Join(skillsDir, "SKILL.md")
+	os.WriteFile(skillFile, []byte("forbidden content"), 0o644)
+
+	// Create a normal file
+	normalFile := filepath.Join(tmpDir, "report.txt")
+	os.WriteFile(normalFile, []byte("allowed content"), 0o644)
+
+	// Test with deny patterns: block anything under skills/
+	denyPatterns := []*regexp.Regexp{regexp.MustCompile(`^skills(/.*)?$`)}
+
+	t.Run("WriteFile blocked", func(t *testing.T) {
+		tool := NewWriteFileTool(tmpDir, true, nil, denyPatterns)
+		args := map[string]any{
+			"path":    "skills/new-skill.md",
+			"content": "hacker stuff",
+		}
+		result := tool.Execute(ctx, args)
+		if !result.IsError {
+			t.Fatal("Expected error when writing to denied path, but got success")
+		}
+		if !strings.Contains(result.ForLLM, "access denied") {
+			t.Errorf("Expected 'access denied' error, got: %s", result.ForLLM)
+		}
+	})
+
+	t.Run("ReadFile blocked", func(t *testing.T) {
+		tool := NewReadFileTool(tmpDir, true, 0, nil, denyPatterns)
+		args := map[string]any{"path": "skills/secret-skill/SKILL.md"}
+		result := tool.Execute(ctx, args)
+		if !result.IsError {
+			t.Fatal("Expected error when reading from denied path, but got success")
+		}
+	})
+
+	t.Run("ListDir blocked", func(t *testing.T) {
+		tool := NewListDirTool(tmpDir, true, nil, denyPatterns)
+		args := map[string]any{"path": "skills"}
+		result := tool.Execute(ctx, args)
+		if !result.IsError {
+			t.Fatal("Expected error when listing denied path, but got success")
+		}
+	})
+
+	t.Run("Normal file allowed", func(t *testing.T) {
+		tool := NewReadFileTool(tmpDir, true, 0, nil, denyPatterns)
+		args := map[string]any{"path": "report.txt"}
+		result := tool.Execute(ctx, args)
+		if result.IsError {
+			t.Fatalf("Expected success for normal file, got error: %s", result.ForLLM)
+		}
+		if !strings.Contains(result.ForLLM, "allowed content") {
+			t.Errorf("Got unexpected content: %s", result.ForLLM)
+		}
+	})
+}
diff --git a/pkg/tools/registry.go b/pkg/tools/registry.go
index bb179509d..b8e9bd3e2 100644
--- a/pkg/tools/registry.go
+++ b/pkg/tools/registry.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"sort"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"time"
@@ -440,7 +441,22 @@ func (r *ToolRegistry) Filter(whitelist []string, enabled bool) {
 
 	removed := 0
 	for name := range r.tools {
-		if _, allowed := whitelistMap[name]; !allowed {
+		allowed := false
+		if _, exact := whitelistMap[name]; exact {
+			allowed = true
+		} else {
+			// Check for prefix matches (e.g. "monday" matches "mcp_monday_...")
+			for _, w := range whitelist {
+				// Match exact (redundant but safe) or prefix with underscore
+				// We also check for "mcp_" prefix specifically to support MCP tool grouping
+				if strings.HasPrefix(name, "mcp_"+w+"_") || strings.HasPrefix(name, "tool_"+w+"_") || strings.HasPrefix(name, w+"_") {
+					allowed = true
+					break
+				}
+			}
+		}
+
+		if !allowed {
 			delete(r.tools, name)
 			removed++
 		}
diff --git a/pkg/tools/registry_test.go b/pkg/tools/registry_test.go
index 16bd30928..3ca4cee4b 100644
--- a/pkg/tools/registry_test.go
+++ b/pkg/tools/registry_test.go
@@ -759,3 +759,42 @@ func TestToolRegistry_ExecuteWithContext_SanitizesInlineMediaWithoutStore(t *tes
 		t.Fatalf("expected inline media omission note, got %q", result.ForLLM)
 	}
 }
+
+func TestToolRegistry_Filter_SupportsPrefix(t *testing.T) {
+	r := NewToolRegistry()
+	r.Register(newMockTool("read_file", "core tool"))
+	r.Register(newMockTool("write_file", "core tool"))
+	r.Register(newMockTool("mcp_monday_get_items", "mcp tool"))
+	r.Register(newMockTool("mcp_harvest_get_entries", "mcp tool"))
+	r.Register(newMockTool("tool_search_regex", "discovery tool"))
+
+	whitelist := []string{"read_file", "monday", "search"}
+	r.Filter(whitelist, true)
+
+	// expected: read_file (exact), mcp_monday_get_items (mcp_monday_ prefix), tool_search_regex (tool_search_ prefix)
+	if r.Count() != 3 {
+		t.Errorf("expected 3 tools after filtering, got %d: %v", r.Count(), r.List())
+	}
+
+	allowed := r.List()
+	expected := map[string]bool{
+		"read_file":            true,
+		"mcp_monday_get_items": true,
+		"tool_search_regex":    true,
+	}
+
+	for _, name := range allowed {
+		if !expected[name] {
+			t.Errorf("tool %q should have been filtered out", name)
+		}
+		delete(expected, name)
+	}
+
+	if len(expected) > 0 {
+		var missing []string
+		for m := range expected {
+			missing = append(missing, m)
+		}
+		t.Errorf("missing expected tools after filter: %v", missing)
+	}
+}
diff --git a/pkg/tools/send_file.go b/pkg/tools/send_file.go
index 44198381e..6afc4b09d 100644
--- a/pkg/tools/send_file.go
+++ b/pkg/tools/send_file.go
@@ -23,6 +23,7 @@ type SendFileTool struct {
 	maxFileSize int
 	mediaStore  media.MediaStore
 	allowPaths  []*regexp.Regexp
+	denyPaths   []*regexp.Regexp
 
 	defaultChannel string
 	defaultChatID  string
@@ -33,21 +34,26 @@ func NewSendFileTool(
 	restrict bool,
 	maxFileSize int,
 	store media.MediaStore,
-	allowPaths ...[]*regexp.Regexp,
+	configs ...[]*regexp.Regexp,
 ) *SendFileTool {
 	if maxFileSize <= 0 {
 		maxFileSize = config.DefaultMaxMediaSize
 	}
-	var patterns []*regexp.Regexp
-	if len(allowPaths) > 0 {
-		patterns = allowPaths[0]
+	var allowPatterns []*regexp.Regexp
+	var denyPatterns []*regexp.Regexp
+	if len(configs) > 0 {
+		allowPatterns = configs[0]
+	}
+	if len(configs) > 1 {
+		denyPatterns = configs[1]
 	}
 	return &SendFileTool{
 		workspace:   workspace,
 		restrict:    restrict,
 		maxFileSize: maxFileSize,
 		mediaStore:  store,
-		allowPaths:  patterns,
+		allowPaths:  allowPatterns,
+		denyPaths:   denyPatterns,
 	}
 }
 
@@ -105,7 +111,7 @@ func (t *SendFileTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		return ErrorResult("media store not configured")
 	}
 
-	resolved, err := validatePathWithAllowPaths(path, t.workspace, t.restrict, t.allowPaths)
+	resolved, err := validatePathWithConfigs(path, t.workspace, t.restrict, t.allowPaths, t.denyPaths)
 	if err != nil {
 		return ErrorResult(fmt.Sprintf("invalid path: %v", err))
 	}
diff --git a/web/backend/api/skills.go b/web/backend/api/skills.go
index 608672172..481a52858 100644
--- a/web/backend/api/skills.go
+++ b/web/backend/api/skills.go
@@ -609,7 +609,7 @@ func findWorkspaceSkillByDirectory(cfg *config.Config, directory string) *skillS
 }
 
 func findWorkspaceSkillInfoByDirectory(workspace, directory string) *skills.SkillInfo {
-	loader := skills.NewSkillsLoader(workspace, "", "")
+	loader := skills.NewSkillsLoader(workspace, "", "", "", nil, false)
 	for _, skill := range loader.ListSkills() {
 		if skill.Source != "workspace" {
 			continue

From 3d621b6401d4bc5f10e4f2f8bbc1d7f430505303 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Fri, 27 Mar 2026 17:17:41 +0100
Subject: [PATCH 12/25] chore: minor configuration updates

---
 pkg/agent/context_cache_test.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkg/agent/context_cache_test.go b/pkg/agent/context_cache_test.go
index a2cdf2b54..49ea10d6d 100644
--- a/pkg/agent/context_cache_test.go
+++ b/pkg/agent/context_cache_test.go
@@ -711,7 +711,7 @@ func TestBuildMessages_IncludesMediaOnlyCurrentMessage(t *testing.T) {
 	tmpDir := setupWorkspace(t, nil)
 	defer os.RemoveAll(tmpDir)
 
-	cb := NewContextBuilder(tmpDir)
+	cb := NewContextBuilder(tmpDir, tmpDir)
 	msgs := cb.BuildMessages(
 		nil,
 		"",

From 253412a5260841a4d5faed844b594c0b8dd7b450 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Fri, 27 Mar 2026 17:52:29 +0100
Subject: [PATCH 13/25] fix(agent): inject media store in isolation and fix
 config unmarshal panic

---
 pkg/agent/loop.go    |  3 +++
 pkg/config/config.go | 23 +++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index b01038a8d..e4f6abc64 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -1469,6 +1469,9 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 			// Set its ID to match the routed agent so prompts and logs match
 			agent.ID = route.AgentID
 
+			// Inject media store so tools (like send_file) can function
+			agent.Tools.SetMediaStore(al.mediaStore)
+
 			// Re-register shared tools (web, message, spawn) to this transient agent
 			// We pass a mini-registry containing only this agent
 			registerSharedTools(al, al.cfg, al.bus, &AgentRegistry{agents: map[string]*AgentInstance{agent.ID: agent}}, baseAgent.Provider)
diff --git a/pkg/config/config.go b/pkg/config/config.go
index d4ddb9354..4dca6ba69 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -1270,6 +1270,29 @@ func (c *Config) SecurityCopyFrom(path string) error {
 	return loadSecurityConfig(c, securityPath(path))
 }
 
+func MergeAPIKeys(apiKey string, apiKeys []string) []string {
+	seen := make(map[string]struct{})
+	var all []string
+
+	if k := strings.TrimSpace(apiKey); k != "" {
+		if _, exists := seen[k]; !exists {
+			seen[k] = struct{}{}
+			all = append(all, k)
+		}
+	}
+
+	for _, k := range apiKeys {
+		if trimmed := strings.TrimSpace(k); trimmed != "" && trimmed != "[NOT_HERE]" {
+			if _, exists := seen[trimmed]; !exists {
+				seen[trimmed] = struct{}{}
+				all = append(all, trimmed)
+			}
+		}
+	}
+
+	return all
+}
+
 // expandMultiKeyModels expands ModelConfig entries with multiple API keys into
 // separate entries for key-level failover. Each key gets its own ModelConfig entry,
 // and the original entry's fallbacks are set up to chain through the expanded entries.

From afebbd36507bf7ab022e8782dc0af724e61a4a02 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Fri, 27 Mar 2026 22:06:12 +0100
Subject: [PATCH 14/25] fixes

---
 pkg/agent/loop.go         | 51 +++++++++++++++++++++++++++++++++++++++
 pkg/agent/loop_test.go    | 40 ++++++++++++++++++++++++++++++
 pkg/channels/http/http.go | 45 ++++++++++++++++++++++++++++++++++
 pkg/channels/manager.go   |  3 +++
 pkg/gateway/gateway.go    |  6 +++--
 5 files changed, 143 insertions(+), 2 deletions(-)
 create mode 100644 pkg/channels/http/http.go

diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index e4f6abc64..b25203c37 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -111,6 +111,7 @@ type continuationTarget struct {
 const (
 	defaultResponse            = "The model returned an empty response. This may indicate a provider error or token limit."
 	toolLimitResponse          = "I've reached `max_tool_iterations` without a final response. Increase `max_tool_iterations` in config.json if this task needs more tool steps."
+	toolRepeatLoopResponse     = "Detected repeated tool calls without progress; stopping to avoid an infinite loop."
 	handledToolResponseSummary = "Requested output delivered via tool attachment."
 	sessionKeyAgentPrefix      = "agent::"
 	metadataKeyAccountID       = "account_id"
@@ -1914,6 +1915,9 @@ func (al *AgentLoop) runTurn(ctx context.Context, ts *turnState) (turnResult, er
 	}
 	pendingMessages := append([]providers.Message(nil), ts.opts.InitialSteeringMessages...)
 	var finalContent string
+	lastToolCallsFingerprint := ""
+	consecutiveRepeatedToolCalls := 0
+	const maxConsecutiveRepeatedToolCalls = 3
 
 turnLoop:
 	for ts.currentIteration() < ts.agent.MaxIterations || len(pendingMessages) > 0 || func() bool {
@@ -2411,6 +2415,53 @@ turnLoop:
 				"iteration": iteration,
 			})
 
+		// Guardrail: if the model keeps requesting the exact same tool calls
+		// over and over (often due to missing/filtered tool results), stop
+		// early instead of running until max_tool_iterations.
+		type toolCallFP struct {
+			Name string          `json:"name"`
+			Args json.RawMessage `json:"args"`
+		}
+		fpParts := make([]toolCallFP, 0, len(normalizedToolCalls))
+		fingerprintBytes := make([]byte, 0)
+		for _, tc := range normalizedToolCalls {
+			argsJSON, err := json.Marshal(tc.Arguments)
+			if err != nil {
+				continue
+			}
+			fpParts = append(fpParts, toolCallFP{
+				Name: tc.Name,
+				Args: json.RawMessage(argsJSON),
+			})
+		}
+		if len(fpParts) > 0 {
+			if fp, err := json.Marshal(fpParts); err == nil {
+				fingerprintBytes = fp
+			}
+		}
+		if len(fingerprintBytes) > 0 {
+			toolCallsFingerprint := string(fingerprintBytes)
+			if toolCallsFingerprint == lastToolCallsFingerprint {
+				consecutiveRepeatedToolCalls++
+			} else {
+				lastToolCallsFingerprint = toolCallsFingerprint
+				consecutiveRepeatedToolCalls = 1
+			}
+
+			if consecutiveRepeatedToolCalls >= maxConsecutiveRepeatedToolCalls {
+				turnStatus = TurnEndStatusError
+				finalContent = toolRepeatLoopResponse
+				logger.WarnCF("agent", "Stopping repeated tool call loop",
+					map[string]any{
+						"agent_id":            ts.agent.ID,
+						"fingerprint_repeats": consecutiveRepeatedToolCalls,
+						"tools":               toolNames,
+						"iteration":           iteration,
+					})
+				break turnLoop
+			}
+		}
+
 		allResponsesHandled := len(normalizedToolCalls) > 0
 		assistantMsg := providers.Message{
 			Role:             "assistant",
diff --git a/pkg/agent/loop_test.go b/pkg/agent/loop_test.go
index cc81f181c..7fc7dcb0b 100644
--- a/pkg/agent/loop_test.go
+++ b/pkg/agent/loop_test.go
@@ -2113,6 +2113,46 @@ func TestAgentLoop_ToolLimitUsesDedicatedFallback(t *testing.T) {
 	}
 }
 
+func TestAgentLoop_ToolRepeatLoopBreaksEarly(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace: tmpDir,
+				ModelName: "test-model",
+				MaxTokens: 4096,
+				// Keep this high so the loop-breaker (not the iteration limit)
+				// is what terminates the turn.
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &toolLimitOnlyProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	al.RegisterTool(&toolLimitTestTool{})
+
+	response, err := al.ProcessDirectWithChannel(
+		context.Background(),
+		"hello",
+		"tool-repeat-loop",
+		"test",
+		"direct",
+	)
+	if err != nil {
+		t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+	}
+	if response != toolRepeatLoopResponse {
+		t.Fatalf("response = %q, want %q", response, toolRepeatLoopResponse)
+	}
+}
+
 // TestProcessDirectWithChannel_TriggersMCPInitialization verifies that
 // ProcessDirectWithChannel triggers MCP initialization when MCP is enabled.
 // Note: Manager is only initialized when at least one MCP server is configured
diff --git a/pkg/channels/http/http.go b/pkg/channels/http/http.go
new file mode 100644
index 000000000..403e1ce23
--- /dev/null
+++ b/pkg/channels/http/http.go
@@ -0,0 +1,45 @@
+package http
+
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func init() {
+	channels.RegisterFactory("http", NewHTTPChannel)
+}
+
+type HTTPChannel struct {
+	*channels.BaseChannel
+}
+
+func NewHTTPChannel(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+	bc := channels.NewBaseChannel("http", nil, b, nil)
+	return &HTTPChannel{
+		BaseChannel: bc,
+	}, nil
+}
+
+func (c *HTTPChannel) Start(ctx context.Context) error {
+	c.SetRunning(true)
+	return nil
+}
+
+func (c *HTTPChannel) Stop(ctx context.Context) error {
+	c.SetRunning(false)
+	return nil
+}
+
+func (c *HTTPChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	logger.InfoCF("channels", "HTTP channel received outbound message", map[string]any{
+		"chat_id": msg.ChatID,
+		"content": msg.Content,
+	})
+	// For synchronous HTTP, the response is usually handled by the caller of ProcessDirectWithChannel.
+	// Asynchronous messages (e.g. from subagents) will just be logged here for now.
+	return nil
+}
diff --git a/pkg/channels/manager.go b/pkg/channels/manager.go
index 6d9f5eda8..29705e9bf 100644
--- a/pkg/channels/manager.go
+++ b/pkg/channels/manager.go
@@ -430,6 +430,9 @@ func (m *Manager) initChannels(channels *config.ChannelsConfig) error {
 		m.initChannel("vk", "VK")
 	}
 
+	// Always initialize HTTP channel as it is used for synchronous gateway chat
+	m.initChannel("http", "HTTP")
+
 	logger.InfoCF("channels", "Channel initialization completed", map[string]any{
 		"enabled_channels": len(m.channels),
 	})
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
index 397091d30..ea1997a43 100644
--- a/pkg/gateway/gateway.go
+++ b/pkg/gateway/gateway.go
@@ -21,6 +21,7 @@ import (
 	_ "github.com/sipeed/picoclaw/pkg/channels/dingtalk"
 	_ "github.com/sipeed/picoclaw/pkg/channels/discord"
 	_ "github.com/sipeed/picoclaw/pkg/channels/feishu"
+	_ "github.com/sipeed/picoclaw/pkg/channels/http"
 	_ "github.com/sipeed/picoclaw/pkg/channels/irc"
 	_ "github.com/sipeed/picoclaw/pkg/channels/line"
 	_ "github.com/sipeed/picoclaw/pkg/channels/maixcam"
@@ -227,10 +228,11 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error
 	if cfg.Gateway.ChatEnabled {
 		runningServices.HealthServer.SetChatFunc(func(ctx context.Context, message, sessionID, chatID string) (string, error) {
 			if sessionID == "" {
-				sessionID = "http-chat"
+				sessionID = fmt.Sprintf("chat-%s", time.Now().Format("20060102-150405"))
 			}
 			if chatID == "" {
-				chatID = "chat"
+				// Default to sessionID to ensure isolation
+				chatID = sessionID
 			}
 			return agentLoop.ProcessDirectWithChannel(ctx, message, sessionID, "http", chatID)
 		})

From db2349cf4d7e81e34ee0e4c5ede65fcf1de1b474 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Fri, 27 Mar 2026 22:50:21 +0100
Subject: [PATCH 15/25] feat(isolation): further hardening for agent loop and
 tools

---
 pkg/agent/isolation_tools_test.go |   4 +-
 pkg/agent/loop.go                 | 172 ++++++++++++++++--------------
 pkg/agent/loop_test.go            |   2 +-
 pkg/tools/shell.go                |  16 ++-
 4 files changed, 108 insertions(+), 86 deletions(-)

diff --git a/pkg/agent/isolation_tools_test.go b/pkg/agent/isolation_tools_test.go
index 21bd810a5..989cd21d8 100644
--- a/pkg/agent/isolation_tools_test.go
+++ b/pkg/agent/isolation_tools_test.go
@@ -195,8 +195,8 @@ func TestProcessMessage_IsolatedTenant_UsesPrivateWorkspace(t *testing.T) {
 	}
 
 	// Verify history is in the base sessions directory with the isolated key
-	// agent:::main:tenant-A becomes agent___main_tenant-A
-	isoSessionPath := filepath.Join(tmpDir, "sessions", "agent___main_tenant-A.jsonl")
+	// agent:main:tenant-A becomes agent_main_tenant-A
+	isoSessionPath := filepath.Join(tmpDir, "sessions", "agent_main_tenant-A.jsonl")
 	if _, err := os.Stat(isoSessionPath); os.IsNotExist(err) {
 		t.Errorf("expected history at %s to exist", isoSessionPath)
 	} else {
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index b25203c37..446283ed2 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -113,7 +113,7 @@ const (
 	toolLimitResponse          = "I've reached `max_tool_iterations` without a final response. Increase `max_tool_iterations` in config.json if this task needs more tool steps."
 	toolRepeatLoopResponse     = "Detected repeated tool calls without progress; stopping to avoid an infinite loop."
 	handledToolResponseSummary = "Requested output delivered via tool attachment."
-	sessionKeyAgentPrefix      = "agent::"
+	sessionKeyAgentPrefix      = "agent"
 	metadataKeyAccountID       = "account_id"
 	metadataKeyGuildID         = "guild_id"
 	metadataKeyTeamID          = "team_id"
@@ -1430,64 +1430,14 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 		return al.processSystemMessage(ctx, msg)
 	}
 
-	route, baseAgent, routeErr := al.resolveMessageRoute(msg)
+	route, _, routeErr := al.resolveMessageRoute(msg)
 	if routeErr != nil {
 		return "", routeErr
 	}
 
-	agent := baseAgent
-	isolationID := msg.ChatID
-	if isolationID != "" && isolationID != "direct" {
-		// Check agent instance cache first (keyed by channel:chatID)
-		cacheKey := msg.Channel + ":" + isolationID
-		if cached, ok := al.agentCache.Load(cacheKey); ok {
-			agent = cached.(*AgentInstance)
-			// Update last access time for TTL tracking
-			al.lastCacheCheck.Store(cacheKey, time.Now())
-
-			logger.InfoCF("agent", "Reusing cached agent instance", map[string]any{
-				"agent_id":     agent.ID,
-				"cache_key":    cacheKey,
-				"isolation_id": isolationID,
-			})
-		} else {
-			// Create a transient isolated instance for this chat session
-			// This ensures workspace, memory, and sessions are private to the chat_id.
-
-			// Determine the original config for this agent to preserve its specialized prompt/skills
-			var ac *config.AgentConfig
-			for i := range al.cfg.Agents.List {
-				if routing.NormalizeAgentID(al.cfg.Agents.List[i].ID) == route.AgentID {
-					ac = &al.cfg.Agents.List[i]
-					break
-				}
-			}
-
-			// Create a new instance with the isolationID
-			// NewAgentInstance uses isolationID to sub-path the workspace
-			agent = NewAgentInstance(ac, &al.cfg.Agents.Defaults, al.cfg, baseAgent.Provider, isolationID)
-
-			// Set its ID to match the routed agent so prompts and logs match
-			agent.ID = route.AgentID
-
-			// Inject media store so tools (like send_file) can function
-			agent.Tools.SetMediaStore(al.mediaStore)
-
-			// Re-register shared tools (web, message, spawn) to this transient agent
-			// We pass a mini-registry containing only this agent
-			registerSharedTools(al, al.cfg, al.bus, &AgentRegistry{agents: map[string]*AgentInstance{agent.ID: agent}}, baseAgent.Provider)
-
-			// Cache this agent instance per chat session
-			al.agentCache.Store(cacheKey, agent)
-			al.lastCacheCheck.Store(cacheKey, time.Now())
-
-			logger.InfoCF("agent", "Created isolated transient agent", map[string]any{
-				"agent_id":     agent.ID,
-				"cache_key":    cacheKey,
-				"isolation_id": isolationID,
-				"workspace":    agent.Workspace,
-			})
-		}
+	agent, err := al.getOrCreateIsolatedAgent(route.AgentID, msg.Channel, msg.ChatID)
+	if err != nil {
+		return "", err
 	}
 
 	// Reset message-tool state for this round so we don't skip publishing due to a previous round.
@@ -1609,6 +1559,68 @@ func (al *AgentLoop) requeueInboundMessage(msg bus.InboundMessage) error {
 	})
 }
 
+func (al *AgentLoop) getOrCreateIsolatedAgent(agentID, channel, isolationID string) (*AgentInstance, error) {
+	if isolationID == "" || isolationID == "direct" {
+		agent, ok := al.GetRegistry().GetAgent(agentID)
+		if !ok {
+			agent = al.GetRegistry().GetDefaultAgent()
+		}
+		if agent == nil {
+			return nil, fmt.Errorf("no agent available for id %s", agentID)
+		}
+		return agent, nil
+	}
+
+	cacheKey := channel + ":" + isolationID
+	if cached, ok := al.agentCache.Load(cacheKey); ok {
+		agent := cached.(*AgentInstance)
+		al.lastCacheCheck.Store(cacheKey, time.Now())
+		return agent, nil
+	}
+
+	// Create a transient isolated instance for this chat session
+	// This ensures workspace, memory, and sessions are private to the chat_id.
+
+	// Determine the original config for this agent to preserve its specialized prompt/skills
+	var ac *config.AgentConfig
+	for i := range al.cfg.Agents.List {
+		if routing.NormalizeAgentID(al.cfg.Agents.List[i].ID) == agentID {
+			ac = &al.cfg.Agents.List[i]
+			break
+		}
+	}
+
+	baseAgent, ok := al.GetRegistry().GetAgent(agentID)
+	if !ok {
+		baseAgent = al.GetRegistry().GetDefaultAgent()
+	}
+	if baseAgent == nil {
+		return nil, fmt.Errorf("base agent %s not found", agentID)
+	}
+
+	agent := NewAgentInstance(ac, &al.cfg.Agents.Defaults, al.cfg, baseAgent.Provider, isolationID)
+	agent.ID = agentID
+
+	// Inject media store so tools (like send_file) can function
+	agent.Tools.SetMediaStore(al.mediaStore)
+
+	// Re-register shared tools (web, message, spawn) to this transient agent
+	registerSharedTools(al, al.cfg, al.bus, &AgentRegistry{agents: map[string]*AgentInstance{agent.ID: agent}}, baseAgent.Provider)
+
+	// Cache this agent instance per chat session
+	al.agentCache.Store(cacheKey, agent)
+	al.lastCacheCheck.Store(cacheKey, time.Now())
+
+	logger.InfoCF("agent", "Created isolated transient agent", map[string]any{
+		"agent_id":     agent.ID,
+		"cache_key":    cacheKey,
+		"isolation_id": isolationID,
+		"workspace":    agent.Workspace,
+	})
+
+	return agent, nil
+}
+
 func (al *AgentLoop) processSystemMessage(
 	ctx context.Context,
 	msg bus.InboundMessage,
@@ -1654,14 +1666,18 @@ func (al *AgentLoop) processSystemMessage(
 		return "", nil
 	}
 
-	// Use default agent for system messages
-	agent := al.GetRegistry().GetDefaultAgent()
-	if agent == nil {
-		return "", fmt.Errorf("no default agent for system message")
+	// Use default agent for system messages, but lookup/create isolated tenant instances
+	// that match the origin of the follow-up task. This ensures workspace isolation.
+	agent, err := al.getOrCreateIsolatedAgent(routing.DefaultAgentID, originChannel, originChatID)
+	if err != nil {
+		return "", err
 	}
 
-	// Use the origin session for context
-	sessionKey := routing.BuildAgentMainSessionKey(agent.ID)
+	// Use provided session key if available, otherwise fall back to main
+	sessionKey := msg.SessionKey
+	if sessionKey == "" {
+		sessionKey = routing.BuildAgentMainSessionKey(agent.ID)
+	}
 
 	return al.runAgentLoop(ctx, agent, processOptions{
 		SessionKey:      sessionKey,
@@ -2357,21 +2373,16 @@ turnLoop:
 			},
 		)
 
-		llmResponseFields := map[string]any{
-			"agent_id":       ts.agent.ID,
-			"iteration":      iteration,
-			"content_chars":  len(response.Content),
-			"tool_calls":     len(response.ToolCalls),
-			"reasoning":      response.Reasoning,
-			"target_channel": al.targetReasoningChannelID(ts.channel),
-			"channel":        ts.channel,
-		}
-		if response.Usage != nil {
-			llmResponseFields["prompt_tokens"] = response.Usage.PromptTokens
-			llmResponseFields["completion_tokens"] = response.Usage.CompletionTokens
-			llmResponseFields["total_tokens"] = response.Usage.TotalTokens
-		}
-		logger.DebugCF("agent", "LLM response", llmResponseFields)
+		logger.DebugCF("agent", "LLM response",
+			map[string]any{
+				"agent_id":       ts.agent.ID,
+				"iteration":      iteration,
+				"content_chars":  len(response.Content),
+				"tool_calls":     len(response.ToolCalls),
+				"reasoning":      response.Reasoning,
+				"target_channel": al.targetReasoningChannelID(ts.channel),
+				"channel":        ts.channel,
+			})
 
 		if len(response.ToolCalls) == 0 || gracefulTerminal {
 			responseContent := response.Content
@@ -2664,10 +2675,11 @@ turnLoop:
 				pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
 				defer pubCancel()
 				_ = al.bus.PublishInbound(pubCtx, bus.InboundMessage{
-					Channel:  "system",
-					SenderID: fmt.Sprintf("async:%s", asyncToolName),
-					ChatID:   fmt.Sprintf("%s:%s", ts.channel, ts.chatID),
-					Content:  content,
+					Channel:    "system",
+					SenderID:   fmt.Sprintf("async:%s", asyncToolName),
+					ChatID:     fmt.Sprintf("%s:%s", ts.channel, ts.chatID),
+					Content:    content,
+					SessionKey: ts.opts.SessionKey,
 				})
 			}
 
diff --git a/pkg/agent/loop_test.go b/pkg/agent/loop_test.go
index 7fc7dcb0b..ce1f26709 100644
--- a/pkg/agent/loop_test.go
+++ b/pkg/agent/loop_test.go
@@ -1400,7 +1400,7 @@ func TestProcessMessage_UsesRouteSessionKey(t *testing.T) {
 	}
 
 	// With chatID isolation, session key is derived from chatID
-	sessionKey := fmt.Sprintf("agent:::main:%s", msg.ChatID)
+	sessionKey := fmt.Sprintf("agent:main:%s", msg.ChatID)
 
 	defaultAgent := al.registry.GetDefaultAgent()
 	if defaultAgent == nil {
diff --git a/pkg/tools/shell.go b/pkg/tools/shell.go
index d2971f3f8..96200b9ff 100644
--- a/pkg/tools/shell.go
+++ b/pkg/tools/shell.go
@@ -1061,18 +1061,28 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
 		// Web URL schemes whose path components (starting with //) should be exempt
 		// from workspace sandbox checks. file: is intentionally excluded so that
 		// file:// URIs are still validated against the workspace boundary.
-		webSchemes := []string{"http:", "https:", "ftp:", "ftps:", "sftp:", "ssh:", "git:"}
+		webSchemes := []string{"http:", "https:", "ftp:", "ftps:", "ssh:", "git:", "sftp:"}
 
 		matchIndices := absolutePathPattern.FindAllStringIndex(cmd, -1)
 
 		for _, loc := range matchIndices {
 			raw := cmd[loc[0]:loc[1]]
 
+			// Check if this is truly the start of a path component.
+			// It should be at the start of the command or preceded by a shell delimiter.
+			if loc[0] > 0 {
+				prev := cmd[loc[0]-1]
+				// Typical shell delimiters that separate command arguments or environment variables.
+				// We include space-like chars, basic separators, and assignment equals.
+				// We also include ':' because it precedes paths in lists ($PATH) and URLs (file://, https://).
+				if !strings.ContainsAny(string(prev), " \t\n\r;|\"&!<>(){}=[]':") {
+					continue
+				}
+			}
+
 			// Skip URL path components that look like they're from web URLs.
 			// When a URL like "https://github.com" is parsed, the regex captures
 			// "//github.com" as a match (the path portion after "https:").
-			// Use the exact match position (loc[0]) so that duplicate //path substrings
-			// in the same command are each evaluated at their own position.
 			if strings.HasPrefix(raw, "//") && loc[0] > 0 {
 				before := cmd[:loc[0]]
 				isWebURL := false

From 56478a031b334956838452656f29795c4b48d4e0 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Sat, 28 Mar 2026 13:47:35 +0100
Subject: [PATCH 16/25] added k3s deployment on RPi

---
 .dockerignore         |   2 +-
 docker/Dockerfile.rpi |  68 +++++
 k3s/configmap.yaml    | 581 ++++++++++++++++++++++++++++++++++++++++++
 k3s/deployment.yaml   |  55 ++++
 k3s/pvc.yaml          |  11 +
 k3s/service.yaml      |  13 +
 6 files changed, 729 insertions(+), 1 deletion(-)
 create mode 100644 docker/Dockerfile.rpi
 create mode 100644 k3s/configmap.yaml
 create mode 100644 k3s/deployment.yaml
 create mode 100644 k3s/pvc.yaml
 create mode 100644 k3s/service.yaml

diff --git a/.dockerignore b/.dockerignore
index d632da5ea..f169f9361 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -2,7 +2,7 @@
 .gitignore
 build/
 .picoclaw/
-config/
+# config/
 .env
 .env.example
 *.md
diff --git a/docker/Dockerfile.rpi b/docker/Dockerfile.rpi
new file mode 100644
index 000000000..1aa80caf1
--- /dev/null
+++ b/docker/Dockerfile.rpi
@@ -0,0 +1,68 @@
+# ============================================================
+# Stage 1: Build the picoclaw binaries
+# ============================================================
+FROM golang:1.25-alpine AS builder
+
+WORKDIR /app
+
+# Cache dependencies
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source
+COPY . .
+
+# Build main binary for ARM64 (Raspberry Pi)
+# We enable standard JSON and Go-based OLM for Matrix
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -tags goolm,stdjson -ldflags="-s -w" -o bin/picoclaw ./cmd/picoclaw
+
+# Build additional tools from cmd/ as individual binaries (e.g. launcher-tui)
+# This follows your requested tool-building pattern
+RUN set -e; \
+  mkdir -p bin/tools; \
+  for d in $(find cmd -maxdepth 1 -type d -not -path 'cmd' -not -path 'cmd/picoclaw'); do \
+    name=$(basename "$d"); \
+    echo "Building tool: $name"; \
+    CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -tags goolm,stdjson -ldflags="-s -w" -o bin/tools/$name ./$d; \
+  done
+
+# ============================================================
+# Stage 2: Final runtime image - lightweight Alpine
+# ============================================================
+FROM alpine:latest
+
+# Install runtime dependencies as requested
+RUN apk add --no-cache \
+  ca-certificates \
+  openssh-client \
+  bash \
+  tzdata && \
+  update-ca-certificates
+
+WORKDIR /app
+
+# Copy main binary
+COPY --from=builder /app/bin/picoclaw /app/picoclaw
+
+# Copy additional tools (PICOCLAW_HOME typically looks for binaries here)
+RUN mkdir -p /app/bin/tools
+COPY --from=builder /app/bin/tools/ /app/bin/tools/
+RUN chmod -R +x /app/bin/tools || true
+
+# App configuration: use the example template by default
+COPY config/config.example.json ./config.json
+
+# If you have specific MCP skill configurations, copy them here
+# Matching your requested template structure
+RUN mkdir -p ./config
+COPY config/config.example.json ./config/mcp_skills.json
+
+# Initial setup: run onboard to create initial directories and local state
+RUN /app/picoclaw onboard
+
+# Expose Gateway port
+EXPOSE 18790
+
+# Standard entrypoint for PicoClaw
+ENTRYPOINT ["/app/picoclaw"]
+CMD ["gateway"]
diff --git a/k3s/configmap.yaml b/k3s/configmap.yaml
new file mode 100644
index 000000000..d5026734a
--- /dev/null
+++ b/k3s/configmap.yaml
@@ -0,0 +1,581 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: picoclaw-config
+  namespace: agi
+data:
+  config.json: |
+    {
+      "session": {
+        "dm_scope": "per-channel-peer"
+      },
+      "version": 1,
+      "agents": {
+        "defaults": {
+          "workspace": "",
+          "restrict_to_workspace": true,
+          "allow_read_outside_workspace": false,
+          "provider": "",
+          "model_name": "nemotron-3-super-120b-a12b",
+          "max_tokens": 32768,
+          "max_tool_iterations": 50,
+          "summarize_message_threshold": 20,
+          "summarize_token_percent": 75,
+          "steering_mode": "one-at-a-time",
+          "subturn": {
+            "max_depth": 10,
+            "max_concurrent": 5,
+            "default_timeout_minutes": 20,
+            "default_token_budget": 100000,
+            "concurrency_timeout_sec": 10
+          },
+          "tool_feedback": {
+            "enabled": true,
+            "max_args_length": 300
+          }
+        }
+      },
+      "channels": {
+        "whatsapp": {
+          "enabled": false,
+          "bridge_url": "ws://localhost:3001",
+          "use_native": false,
+          "session_store_path": "",
+          "allow_from": [],
+          "reasoning_channel_id": ""
+        },
+        "telegram": {
+          "enabled": true,
+          "token": "REDACTED",
+          "base_url": "",
+          "proxy": "",
+          "allow_from": [
+            "-5274005272",
+            "8271300679"
+          ],
+          "group_trigger": {},
+          "typing": {
+            "enabled": true
+          },
+          "placeholder": {
+            "enabled": true,
+            "text": "Thinking... 💭"
+          },
+          "streaming": {
+            "enabled": true,
+            "throttle_seconds": 3,
+            "min_growth_chars": 200
+          },
+          "reasoning_channel_id": "",
+          "use_markdown_v2": false
+        },
+        "feishu": {
+          "enabled": false,
+          "app_id": "",
+          "allow_from": [],
+          "group_trigger": {},
+          "placeholder": {},
+          "reasoning_channel_id": "",
+          "random_reaction_emoji": null,
+          "is_lark": false
+        },
+        "discord": {
+          "enabled": false,
+          "proxy": "",
+          "allow_from": [],
+          "mention_only": false,
+          "group_trigger": {},
+          "typing": {},
+          "placeholder": {},
+          "reasoning_channel_id": ""
+        },
+        "maixcam": {
+          "enabled": false,
+          "host": "0.0.0.0",
+          "port": 18790,
+          "allow_from": [],
+          "reasoning_channel_id": ""
+        },
+        "qq": {
+          "enabled": false,
+          "app_id": "",
+          "allow_from": [],
+          "group_trigger": {},
+          "max_message_length": 2000,
+          "max_base64_file_size_mib": 0,
+          "send_markdown": false,
+          "reasoning_channel_id": ""
+        },
+        "dingtalk": {
+          "enabled": false,
+          "client_id": "",
+          "allow_from": [],
+          "group_trigger": {},
+          "reasoning_channel_id": ""
+        },
+        "slack": {
+          "enabled": false,
+          "allow_from": [],
+          "group_trigger": {},
+          "typing": {},
+          "placeholder": {},
+          "reasoning_channel_id": ""
+        },
+        "matrix": {
+          "enabled": false,
+          "homeserver": "https://matrix.org",
+          "user_id": "",
+          "join_on_invite": true,
+          "allow_from": [],
+          "group_trigger": {
+            "mention_only": true
+          },
+          "placeholder": {
+            "enabled": true,
+            "text": "Thinking... 💭"
+          },
+          "reasoning_channel_id": ""
+        },
+        "line": {
+          "enabled": false,
+          "webhook_host": "0.0.0.0",
+          "webhook_port": 18791,
+          "webhook_path": "/webhook/line",
+          "allow_from": [],
+          "group_trigger": {
+            "mention_only": true
+          },
+          "typing": {},
+          "placeholder": {},
+          "reasoning_channel_id": ""
+        },
+        "onebot": {
+          "enabled": false,
+          "ws_url": "ws://127.0.0.1:3001",
+          "reconnect_interval": 5,
+          "group_trigger_prefix": null,
+          "allow_from": [],
+          "group_trigger": {},
+          "typing": {},
+          "placeholder": {},
+          "reasoning_channel_id": ""
+        },
+        "wecom": {
+          "enabled": false,
+          "webhook_url": "",
+          "webhook_host": "0.0.0.0",
+          "webhook_port": 18793,
+          "webhook_path": "/webhook/wecom",
+          "allow_from": [],
+          "reply_timeout": 5,
+          "group_trigger": {},
+          "reasoning_channel_id": ""
+        },
+        "wecom_app": {
+          "enabled": false,
+          "corp_id": "",
+          "agent_id": 0,
+          "webhook_host": "0.0.0.0",
+          "webhook_port": 18792,
+          "webhook_path": "/webhook/wecom-app",
+          "allow_from": [],
+          "reply_timeout": 5,
+          "group_trigger": {},
+          "reasoning_channel_id": ""
+        },
+        "wecom_aibot": {
+          "enabled": false,
+          "webhook_path": "/webhook/wecom-aibot",
+          "allow_from": [],
+          "reply_timeout": 5,
+          "max_steps": 10,
+          "welcome_message": "Hello! I'm your AI assistant. How can I help you today?",
+          "processing_message": "⏳ Processing, please wait. The results will be sent shortly.",
+          "reasoning_channel_id": ""
+        },
+        "weixin": {
+          "enabled": false,
+          "base_url": "https://ilinkai.weixin.qq.com/",
+          "cdn_base_url": "https://novac2c.cdn.weixin.qq.com/c2c",
+          "proxy": "",
+          "allow_from": [],
+          "reasoning_channel_id": ""
+        },
+        "pico": {
+          "enabled": true,
+          "allow_token_query": true,
+          "ping_interval": 30,
+          "read_timeout": 60,
+          "write_timeout": 10,
+          "max_connections": 100,
+          "allow_from": [],
+          "placeholder": {}
+        },
+        "pico_client": {
+          "enabled": false,
+          "url": "",
+          "token": "",
+          "allow_from": null
+        },
+        "irc": {
+          "enabled": false,
+          "server": "",
+          "tls": false,
+          "nick": "",
+          "sasl_user": "",
+          "channels": null,
+          "allow_from": null,
+          "group_trigger": {},
+          "typing": {},
+          "reasoning_channel_id": ""
+        }
+      },
+      "model_list": [
+        {
+          "model_name": "glm-4.7",
+          "model": "zhipu/glm-4.7",
+          "api_base": "https://open.bigmodel.cn/api/paas/v4"
+        },
+        {
+          "model_name": "gpt-5.4",
+          "model": "openai/gpt-5.4",
+          "api_base": "https://api.openai.com/v1"
+        },
+        {
+          "model_name": "claude-sonnet-4.6",
+          "model": "anthropic/claude-sonnet-4.6",
+          "api_base": "https://api.anthropic.com/v1"
+        },
+        {
+          "model_name": "deepseek-chat",
+          "model": "deepseek/deepseek-chat",
+          "api_base": "https://api.deepseek.com/v1"
+        },
+        {
+          "model_name": "gemini-2.0-flash",
+          "model": "gemini/gemini-2.0-flash-exp",
+          "api_base": "https://generativelanguage.googleapis.com/v1beta"
+        },
+        {
+          "model_name": "qwen-plus",
+          "model": "qwen/qwen-plus",
+          "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+        },
+        {
+          "model_name": "moonshot-v1-8k",
+          "model": "moonshot/moonshot-v1-8k",
+          "api_base": "https://api.moonshot.cn/v1"
+        },
+        {
+          "model_name": "llama-3.3-70b",
+          "model": "groq/llama-3.3-70b-versatile",
+          "api_base": "https://api.groq.com/openai/v1"
+        },
+        {
+          "model_name": "openrouter-auto",
+          "model": "openrouter/auto",
+          "api_base": "https://openrouter.ai/api/v1"
+        },
+        {
+          "model_name": "openrouter-gpt-5.4",
+          "model": "openrouter/openai/gpt-5.4",
+          "api_base": "https://openrouter.ai/api/v1"
+        },
+        {
+          "model_name": "nemotron-3-super-120b-a12b",
+          "model": "nvidia/nemotron-3-super-120b-a12b",
+          "api_base": "https://integrate.api.nvidia.com/v1",
+          "api_key": "REDACTED"
+        },
+        {
+          "model_name": "azure-grok",
+          "model": "openai/grok-4-fast-non-reasoning",
+          "api_base": "https://TestSJF.openai.azure.com/openai/v1/",
+          "api_key": "REDACTED"
+        },
+        {
+          "model_name": "cerebras-llama-3.3-70b",
+          "model": "cerebras/llama-3.3-70b",
+          "api_base": "https://api.cerebras.ai/v1"
+        },
+        {
+          "model_name": "vivgrid-auto",
+          "model": "vivgrid/auto",
+          "api_base": "https://api.vivgrid.com/v1"
+        },
+        {
+          "model_name": "ark-code-latest",
+          "model": "volcengine/ark-code-latest",
+          "api_base": "https://ark.cn-beijing.volces.com/api/v3"
+        },
+        {
+          "model_name": "doubao-pro",
+          "model": "volcengine/doubao-pro-32k",
+          "api_base": "https://ark.cn-beijing.volces.com/api/v3"
+        },
+        {
+          "model_name": "deepseek-v3",
+          "model": "shengsuanyun/deepseek-v3",
+          "api_base": "https://api.shengsuanyun.com/v1"
+        },
+        {
+          "model_name": "gemini-flash",
+          "model": "antigravity/gemini-3-flash",
+          "auth_method": "oauth"
+        },
+        {
+          "model_name": "copilot-gpt-5.4",
+          "model": "github-copilot/gpt-5.4",
+          "api_base": "http://localhost:4321",
+          "auth_method": "oauth"
+        },
+        {
+          "model_name": "llama3",
+          "model": "ollama/llama3",
+          "api_base": "http://localhost:11434/v1"
+        },
+        {
+          "model_name": "mistral-small",
+          "model": "mistral/mistral-small-latest",
+          "api_base": "https://api.mistral.ai/v1"
+        },
+        {
+          "model_name": "deepseek-v3.2",
+          "model": "avian/deepseek/deepseek-v3.2",
+          "api_base": "https://api.avian.io/v1"
+        },
+        {
+          "model_name": "kimi-k2.5",
+          "model": "avian/moonshotai/kimi-k2.5",
+          "api_base": "https://api.avian.io/v1"
+        },
+        {
+          "model_name": "MiniMax-M2.5",
+          "model": "minimax/MiniMax-M2.5",
+          "api_base": "https://api.minimaxi.com/v1",
+          "extra_body": {
+            "reasoning_split": true
+          }
+        },
+        {
+          "model_name": "LongCat-Flash-Thinking",
+          "model": "longcat/LongCat-Flash-Thinking",
+          "api_base": "https://api.longcat.chat/openai"
+        },
+        {
+          "model_name": "modelscope-qwen",
+          "model": "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
+          "api_base": "https://api-inference.modelscope.cn/v1"
+        },
+        {
+          "model_name": "local-model",
+          "model": "vllm/custom-model",
+          "api_base": "http://localhost:8000/v1"
+        },
+        {
+          "model_name": "azure-gpt5",
+          "model": "azure/my-gpt5-deployment",
+          "api_base": "https://your-resource.openai.azure.com"
+        }
+      ],
+      "gateway": {
+        "host": "0.0.0.0",
+        "port": 18790,
+        "api_key": "picoclaw-secret-123",
+        "chat_enabled": true,
+        "hot_reload": true,
+        "log_level": "info"
+      },
+      "hooks": {
+        "enabled": true,
+        "defaults": {
+          "observer_timeout_ms": 500,
+          "interceptor_timeout_ms": 5000,
+          "approval_timeout_ms": 60000
+        }
+      },
+      "tools": {
+        "filter_sensitive_data": true,
+        "filter_min_length": 8,
+        "allow_read_paths": null,
+        "allow_write_paths": null,
+        "deny_read_paths": [
+          "^skills(/.*)?$"
+        ],
+        "deny_write_paths": [
+          "^skills(/.*)?$"
+        ],
+        "web": {
+          "enabled": true,
+          "brave": {
+            "enabled": false,
+            "max_results": 5
+          },
+          "tavily": {
+            "enabled": false,
+            "base_url": "",
+            "max_results": 5
+          },
+          "duckduckgo": {
+            "enabled": true,
+            "max_results": 5
+          },
+          "perplexity": {
+            "enabled": false,
+            "max_results": 5
+          },
+          "searxng": {
+            "enabled": false,
+            "base_url": "",
+            "max_results": 5
+          },
+          "glm_search": {
+            "enabled": false,
+            "base_url": "https://open.bigmodel.cn/api/paas/v4/web_search",
+            "search_engine": "search_std",
+            "max_results": 5
+          },
+          "baidu_search": {
+            "enabled": false,
+            "base_url": "https://qianfan.baidubce.com/v2/ai_search/web_search",
+            "max_results": 10
+          },
+          "prefer_native": true,
+          "fetch_limit_bytes": 10485760,
+          "format": "plaintext"
+        },
+        "cron": {
+          "enabled": true,
+          "exec_timeout_minutes": 5,
+          "allow_command": true
+        },
+        "exec": {
+          "enabled": true,
+          "enable_deny_patterns": true,
+          "allow_remote": true,
+          "custom_deny_patterns": null,
+          "custom_allow_patterns": null,
+          "timeout_seconds": 60
+        },
+        "skills": {
+          "whitelist_enabled": true,
+          "whitelist": [
+            "weather",
+            "summarize"
+          ],
+          "enabled": true,
+          "registries": {
+            "clawhub": {
+              "enabled": true,
+              "base_url": "https://clawhub.ai",
+              "search_path": "",
+              "skills_path": "",
+              "download_path": "",
+              "timeout": 0,
+              "max_zip_size": 0,
+              "max_response_size": 0
+            },
+            "github": {}
+          },
+          "max_concurrent_searches": 2,
+          "search_cache": {
+            "max_size": 50,
+            "ttl_seconds": 300
+          }
+        },
+        "media_cleanup": {
+          "enabled": true,
+          "max_age_minutes": 30,
+          "interval_minutes": 5
+        },
+        "mcp": {
+          "enabled": true,
+          "discovery": {
+            "enabled": false,
+            "ttl": 5,
+            "max_search_results": 5,
+            "use_bm25": true,
+            "use_regex": false
+          },
+          "servers": {}
+        },
+        "whitelist": [
+          "spawn",
+          "subagent",
+          "read_file",
+          "list_dir",
+          "write_file",
+          "edit_file",
+          "append_file",
+          "exec",
+          "message",
+          "weather",
+          "summarize",
+          "github"
+        ],
+        "whitelist_enabled": true,
+        "append_file": {
+          "enabled": true
+        },
+        "edit_file": {
+          "enabled": true
+        },
+        "find_skills": {
+          "enabled": true
+        },
+        "i2c": {
+          "enabled": false
+        },
+        "install_skill": {
+          "enabled": true
+        },
+        "list_dir": {
+          "enabled": true
+        },
+        "message": {
+          "enabled": true
+        },
+        "read_file": {
+          "enabled": true,
+          "max_read_file_size": 65536
+        },
+        "send_file": {
+          "enabled": true
+        },
+        "spawn": {
+          "enabled": true
+        },
+        "spawn_status": {
+          "enabled": false
+        },
+        "spi": {
+          "enabled": false
+        },
+        "subagent": {
+          "enabled": true
+        },
+        "web_fetch": {
+          "enabled": true
+        },
+        "write_file": {
+          "enabled": true
+        }
+      },
+      "heartbeat": {
+        "enabled": true,
+        "interval": 30
+      },
+      "devices": {
+        "enabled": false,
+        "monitor_usb": true
+      },
+      "voice": {
+        "echo_transcription": false
+      },
+      "build_info": {
+        "version": "0.1.0",
+        "git_commit": "054b55fd",
+        "build_time": "2026-03-23T10:15:13+0100",
+        "go_version": "go1.26.1"
+      }
+    }
diff --git a/k3s/deployment.yaml b/k3s/deployment.yaml
new file mode 100644
index 000000000..e0cb96ac8
--- /dev/null
+++ b/k3s/deployment.yaml
@@ -0,0 +1,55 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: picoclaw-agent
+  namespace: agi
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: picoclaw-agent
+  template:
+    metadata:
+      labels:
+        app: picoclaw-agent
+    spec:
+      # Init container to bootstrap the configuration from the ConfigMap into the Persistent Volume
+      # This answers "how will I copy the config file": the config is copied into the volume on the first run.
+      initContainers:
+      - name: init-config
+        image: busybox:latest
+        command:
+          - sh
+          - -c
+          - |
+            mkdir -p /home/picoclaw/.picoclaw
+            echo "Syncing config.json from ConfigMap..."
+            cp /config-source/config.json /home/picoclaw/.picoclaw/config.json
+            # Ensure the agent has write permissions to its home volume
+            chown -R 1000:1000 /home/picoclaw/.picoclaw
+        volumeMounts:
+        - name: picoclaw-data
+          mountPath: /home/picoclaw/.picoclaw
+        - name: picoclaw-config-source
+          mountPath: /config-source
+      containers:
+      - name: picoclaw-agent
+        image: stevef1uk/picoclaw-rpi:latest
+        imagePullPolicy: Always
+        ports:
+        - containerPort: 18790
+        env:
+        - name: PICOCLAW_HOME
+          value: /home/picoclaw/.picoclaw
+        - name: PICOCLAW_GATEWAY_HOST
+          value: "0.0.0.0"
+        volumeMounts:
+        - name: picoclaw-data
+          mountPath: /home/picoclaw/.picoclaw
+      volumes:
+      - name: picoclaw-data
+        persistentVolumeClaim:
+          claimName: picoclaw-agent-pvc
+      - name: picoclaw-config-source
+        configMap:
+          name: picoclaw-config
diff --git a/k3s/pvc.yaml b/k3s/pvc.yaml
new file mode 100644
index 000000000..9cca70111
--- /dev/null
+++ b/k3s/pvc.yaml
@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: picoclaw-agent-pvc
+  namespace: agi
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 500Mi
diff --git a/k3s/service.yaml b/k3s/service.yaml
new file mode 100644
index 000000000..4eb8b3393
--- /dev/null
+++ b/k3s/service.yaml
@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: picoclaw-agent
+  namespace: agi
+spec:
+  selector:
+    app: picoclaw-agent
+  ports:
+    - protocol: TCP
+      port: 18790
+      targetPort: 18790
+  type: ClusterIP

From 746c3ec02ca92357b05e6b113a859d80f09717b4 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Sat, 28 Mar 2026 15:41:11 +0100
Subject: [PATCH 17/25] Hardening: Relaxed Git push/force restrictions and
 sanitized configuration secrets

---
 k3s/configmap.yaml | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/k3s/configmap.yaml b/k3s/configmap.yaml
index d5026734a..f8d2310f1 100644
--- a/k3s/configmap.yaml
+++ b/k3s/configmap.yaml
@@ -46,7 +46,7 @@ data:
         },
         "telegram": {
           "enabled": true,
-          "token": "REDACTED",
+          "token": "<TELEGRAM_TOKEN>",
           "base_url": "",
           "proxy": "",
           "allow_from": [
@@ -285,13 +285,13 @@ data:
           "model_name": "nemotron-3-super-120b-a12b",
           "model": "nvidia/nemotron-3-super-120b-a12b",
           "api_base": "https://integrate.api.nvidia.com/v1",
-          "api_key": "REDACTED"
+          "api_key": "<NVIDIA_API_KEY>"
         },
         {
           "model_name": "azure-grok",
           "model": "openai/grok-4-fast-non-reasoning",
           "api_base": "https://TestSJF.openai.azure.com/openai/v1/",
-          "api_key": "REDACTED"
+          "api_key": "<AZURE_API_KEY>"
         },
         {
           "model_name": "cerebras-llama-3.3-70b",
@@ -454,7 +454,10 @@ data:
           "enable_deny_patterns": true,
           "allow_remote": true,
           "custom_deny_patterns": null,
-          "custom_allow_patterns": null,
+          "custom_allow_patterns": [
+            "^git\\s+push\\b",
+            "^git\\s+force\\b"
+          ],
           "timeout_seconds": 60
         },
         "skills": {
@@ -497,7 +500,22 @@ data:
             "use_bm25": true,
             "use_regex": false
           },
-          "servers": {}
+          "servers": {
+            "hdn-server": {
+              "enabled": true,
+              "command": "",
+              "type": "sse",
+              "url": "http://hdn-server:8080/mcp"
+            },
+            "n8n-test": {
+              "enabled": true,
+              "type": "sse",
+              "url": "https://n8namber.app.n8n.cloud/mcp/a5747ff8-db9b-4326-8bef-474301f65251",
+              "headers": {
+                "Authorization": "Bearer 97340696-89AE-43B2-B6E2-080E062150C9"
+              }
+            }
+          }
         },
         "whitelist": [
           "spawn",
@@ -511,7 +529,9 @@ data:
           "message",
           "weather",
           "summarize",
-          "github"
+          "github",
+          "hdn-server",
+          "n8n-test"
         ],
         "whitelist_enabled": true,
         "append_file": {

From e0bd93a732e957ed18d19e3510d34c9eecad8115 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Sat, 28 Mar 2026 15:43:15 +0100
Subject: [PATCH 18/25] Security: Migrated API keys to K8s Secrets via file://
 scheme

---
 k3s/configmap.yaml  |  6 +++---
 k3s/deployment.yaml |  6 ++++++
 k3s/secrets.yaml    | 11 +++++++++++
 3 files changed, 20 insertions(+), 3 deletions(-)
 create mode 100644 k3s/secrets.yaml

diff --git a/k3s/configmap.yaml b/k3s/configmap.yaml
index f8d2310f1..4a3b759db 100644
--- a/k3s/configmap.yaml
+++ b/k3s/configmap.yaml
@@ -46,7 +46,7 @@ data:
         },
         "telegram": {
           "enabled": true,
-          "token": "<TELEGRAM_TOKEN>",
+          "token": "file:///etc/picoclaw/secrets/telegram-token",
           "base_url": "",
           "proxy": "",
           "allow_from": [
@@ -285,13 +285,13 @@ data:
           "model_name": "nemotron-3-super-120b-a12b",
           "model": "nvidia/nemotron-3-super-120b-a12b",
           "api_base": "https://integrate.api.nvidia.com/v1",
-          "api_key": "<NVIDIA_API_KEY>"
+          "api_key": "file:///etc/picoclaw/secrets/nvidia-api-key"
         },
         {
           "model_name": "azure-grok",
           "model": "openai/grok-4-fast-non-reasoning",
           "api_base": "https://TestSJF.openai.azure.com/openai/v1/",
-          "api_key": "<AZURE_API_KEY>"
+          "api_key": "file:///etc/picoclaw/secrets/azure-api-key"
         },
         {
           "model_name": "cerebras-llama-3.3-70b",
diff --git a/k3s/deployment.yaml b/k3s/deployment.yaml
index e0cb96ac8..5af999b4c 100644
--- a/k3s/deployment.yaml
+++ b/k3s/deployment.yaml
@@ -46,6 +46,9 @@ spec:
         volumeMounts:
         - name: picoclaw-data
           mountPath: /home/picoclaw/.picoclaw
+        - name: picoclaw-secrets
+          mountPath: /etc/picoclaw/secrets
+          readOnly: true
       volumes:
       - name: picoclaw-data
         persistentVolumeClaim:
@@ -53,3 +56,6 @@ spec:
       - name: picoclaw-config-source
         configMap:
           name: picoclaw-config
+      - name: picoclaw-secrets
+        secret:
+          secretName: picoclaw-secrets
diff --git a/k3s/secrets.yaml b/k3s/secrets.yaml
new file mode 100644
index 000000000..328926b2e
--- /dev/null
+++ b/k3s/secrets.yaml
@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: picoclaw-secrets
+  namespace: default
+type: Opaque
+stringData:
+  # Base64 encoding is handled automatically by K8s when using stringData
+  telegram-token: "YOUR_TELEGRAM_TOKEN_HERE"
+  nvidia-api-key: "YOUR_NVIDIA_API_KEY_HERE"
+  azure-api-key: "YOUR_AZURE_API_KEY_HERE"

From d7532131fae23bbf542d3edcf8ae2e6748e4c1a7 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Sat, 28 Mar 2026 15:43:41 +0100
Subject: [PATCH 19/25] Docs: Added K3s deployment README

---
 k3s/README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 k3s/README.md

diff --git a/k3s/README.md b/k3s/README.md
new file mode 100644
index 000000000..900aee131
--- /dev/null
+++ b/k3s/README.md
@@ -0,0 +1,64 @@
+# PicoClaw K3s Deployment
+
+This directory contains the Kubernetes manifests for deploying the PicoClaw agent on a K3s cluster. The deployment is hardened with workspace isolation and secure secret management.
+
+## 📁 Manifests
+
+- **[deployment.yaml](deployment.yaml)**: Defines the PicoClaw agent deployment, including an init container for configuration syncing and volume mounts for secrets and persistent storage.
+- **[configmap.yaml](configmap.yaml)**: The main agent configuration (Syncs to `config.json`).
+- **[secrets.yaml](secrets.yaml)**: Template for sensitive API keys (Telegram, NVIDIA, Azure, etc.).
+- **[pvc.yaml](pvc.yaml)**: Persistent Volume Claim for agent workspaces and chat history.
+- **[service.yaml](service.yaml)**: Internal service for MCP server communication.
+
+## 🚀 Deployment Steps
+
+### 1. Configure Secrets
+Open **[secrets.yaml](secrets.yaml)** and replace the placeholders with your actual API keys. Then apply it to your cluster:
+
+```bash
+kubectl apply -f secrets.yaml
+```
+
+### 2. Prepare Storage
+Ensure your K3s cluster has a default storage class or configure the **[pvc.yaml](pvc.yaml)** to match your storage provider:
+
+```bash
+kubectl apply -f pvc.yaml
+```
+
+### 3. Deploy the Agent
+Apply the configuration and the deployment:
+
+```bash
+kubectl apply -f configmap.yaml
+kubectl apply -f deployment.yaml
+kubectl apply -f service.yaml
+```
+
+## 🔒 Security Features
+
+### Workspace Isolation
+The agent is configured to restrict all filesystem tools to its respective workspace. The `deployment.yaml` ensures the correct directory structure is initialized before the agent starts.
+
+### Secret Management
+API keys are never stored in the `ConfigMap`. Instead, they are mounted as files from a Kubernetes Secret into `/etc/picoclaw/secrets/`. The agent reads these using the `file://` scheme:
+
+```json
+"token": "file:///etc/picoclaw/secrets/telegram-token"
+```
+
+### Safe Command Execution
+Standard high-risk shell commands are blocked by the `exec` tool's safety guard. Targeted relaxations (e.g., for `git push`) are explicitly added to `custom_allow_patterns` in `configmap.yaml`.
+
+## 🛠️ Management
+
+### Logs
+To view the agent logs:
+```bash
+kubectl logs -f deployment/picoclaw-agent
+```
+
+### Updating Configuration
+1. Modify **[configmap.yaml](configmap.yaml)**.
+2. Apply the change: `kubectl apply -f configmap.yaml`.
+3. Restart the pod: `kubectl rollout restart deployment/picoclaw-agent`.

From 2f58fc3b89b3f94b36ad0c161617ddb2685567ea Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Sat, 28 Mar 2026 16:19:13 +0100
Subject: [PATCH 20/25] Hardening: Finalized K3s deployment with relative
 secret paths and agi namespace

---
 k3s/configmap.yaml  | 8 ++++----
 k3s/deployment.yaml | 2 +-
 k3s/secrets.yaml    | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/k3s/configmap.yaml b/k3s/configmap.yaml
index 4a3b759db..5fe5fff46 100644
--- a/k3s/configmap.yaml
+++ b/k3s/configmap.yaml
@@ -12,7 +12,7 @@ data:
       "version": 1,
       "agents": {
         "defaults": {
-          "workspace": "",
+          "workspace": "/home/picoclaw/.picoclaw",
           "restrict_to_workspace": true,
           "allow_read_outside_workspace": false,
           "provider": "",
@@ -46,7 +46,7 @@ data:
         },
         "telegram": {
           "enabled": true,
-          "token": "file:///etc/picoclaw/secrets/telegram-token",
+          "token": "file://secrets/telegram-token",
           "base_url": "",
           "proxy": "",
           "allow_from": [
@@ -285,13 +285,13 @@ data:
           "model_name": "nemotron-3-super-120b-a12b",
           "model": "nvidia/nemotron-3-super-120b-a12b",
           "api_base": "https://integrate.api.nvidia.com/v1",
-          "api_key": "file:///etc/picoclaw/secrets/nvidia-api-key"
+          "api_key": "file://secrets/nvidia-api-key"
         },
         {
           "model_name": "azure-grok",
           "model": "openai/grok-4-fast-non-reasoning",
           "api_base": "https://TestSJF.openai.azure.com/openai/v1/",
-          "api_key": "file:///etc/picoclaw/secrets/azure-api-key"
+          "api_key": "file://secrets/azure-api-key"
         },
         {
           "model_name": "cerebras-llama-3.3-70b",
diff --git a/k3s/deployment.yaml b/k3s/deployment.yaml
index 5af999b4c..aaa1a8ef7 100644
--- a/k3s/deployment.yaml
+++ b/k3s/deployment.yaml
@@ -47,7 +47,7 @@ spec:
         - name: picoclaw-data
           mountPath: /home/picoclaw/.picoclaw
         - name: picoclaw-secrets
-          mountPath: /etc/picoclaw/secrets
+          mountPath: /home/picoclaw/.picoclaw/secrets
           readOnly: true
       volumes:
       - name: picoclaw-data
diff --git a/k3s/secrets.yaml b/k3s/secrets.yaml
index 328926b2e..217cc0d95 100644
--- a/k3s/secrets.yaml
+++ b/k3s/secrets.yaml
@@ -2,7 +2,7 @@ apiVersion: v1
 kind: Secret
 metadata:
   name: picoclaw-secrets
-  namespace: default
+  namespace: agi
 type: Opaque
 stringData:
   # Base64 encoding is handled automatically by K8s when using stringData

From 4b09745b96876217d1dd3581cbac00338e24bfa4 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Sat, 28 Mar 2026 16:42:30 +0100
Subject: [PATCH 21/25] Fix: Reverted workspace to align internal agent paths

---
 k3s/configmap.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/k3s/configmap.yaml b/k3s/configmap.yaml
index 5fe5fff46..c8567c647 100644
--- a/k3s/configmap.yaml
+++ b/k3s/configmap.yaml
@@ -12,7 +12,7 @@ data:
       "version": 1,
       "agents": {
         "defaults": {
-          "workspace": "/home/picoclaw/.picoclaw",
+          "workspace": "",
           "restrict_to_workspace": true,
           "allow_read_outside_workspace": false,
           "provider": "",

From 42dfb5bdaea1f1b5da0bc95e1bff931b52d450fa Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Thu, 2 Apr 2026 08:05:57 +0200
Subject: [PATCH 22/25] chore: final stabilization fixes for security_shield
 after rebase

---
 pkg/channels/http/http.go         | 4 ++--
 pkg/config/migration.go           | 4 ++--
 pkg/health/server.go              | 7 ++++++-
 pkg/providers/factory_provider.go | 1 +
 web/backend/api/skills.go         | 1 +
 5 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/pkg/channels/http/http.go b/pkg/channels/http/http.go
index 403e1ce23..26470f6d8 100644
--- a/pkg/channels/http/http.go
+++ b/pkg/channels/http/http.go
@@ -34,12 +34,12 @@ func (c *HTTPChannel) Stop(ctx context.Context) error {
 	return nil
 }
 
-func (c *HTTPChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+func (c *HTTPChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]string, error) {
 	logger.InfoCF("channels", "HTTP channel received outbound message", map[string]any{
 		"chat_id": msg.ChatID,
 		"content": msg.Content,
 	})
 	// For synchronous HTTP, the response is usually handled by the caller of ProcessDirectWithChannel.
 	// Asynchronous messages (e.g. from subagents) will just be logged here for now.
-	return nil
+	return nil, nil
 }
diff --git a/pkg/config/migration.go b/pkg/config/migration.go
index 7430050b3..78be9b78b 100644
--- a/pkg/config/migration.go
+++ b/pkg/config/migration.go
@@ -539,7 +539,7 @@ func mergeAPIKeys(apiKey string, apiKeys []string) []string {
 	seen := make(map[string]struct{})
 	var all []string
 
-	if k := strings.TrimSpace(apiKey); k != "" {
+	if k := strings.TrimSpace(apiKey); k != "" && k != "[NOT_HERE]" {
 		if _, exists := seen[k]; !exists {
 			seen[k] = struct{}{}
 			all = append(all, k)
@@ -547,7 +547,7 @@ func mergeAPIKeys(apiKey string, apiKeys []string) []string {
 	}
 
 	for _, k := range apiKeys {
-		if trimmed := strings.TrimSpace(k); trimmed != "" {
+		if trimmed := strings.TrimSpace(k); trimmed != "" && trimmed != "[NOT_HERE]" {
 			if _, exists := seen[trimmed]; !exists {
 				seen[trimmed] = struct{}{}
 				all = append(all, trimmed)
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 736479eda..9410f845e 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -271,9 +271,14 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// HandlerMux defines the interface for an HTTP request multiplexer.
+type HandlerMux interface {
+	HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
+}
+
 // RegisterOnMux registers /health, /ready, /reload and /chat handlers onto the
 // given mux. This allows the health endpoints to be served by a shared HTTP server.
-func (s *Server) RegisterOnMux(mux Mux) {
+func (s *Server) RegisterOnMux(mux HandlerMux) {
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
 	mux.HandleFunc("/reload", s.reloadHandler)
diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index ddad48a94..60311ba18 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -222,6 +222,7 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 		"vivgrid", "volcengine", "vllm", "qwen", "qwen-intl", "qwen-international", "dashscope-intl",
 		"qwen-us", "dashscope-us", "mistral", "avian", "longcat", "modelscope", "novita",
 		"coding-plan", "alibaba-coding", "qwen-coding", "mimo":
+
 		// All other OpenAI-compatible HTTP providers
 		if cfg.APIKey() == "" && cfg.APIBase == "" && !isEmptyAPIKeyAllowed(protocol) {
 			return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
diff --git a/web/backend/api/skills.go b/web/backend/api/skills.go
index 481a52858..329225ce6 100644
--- a/web/backend/api/skills.go
+++ b/web/backend/api/skills.go
@@ -610,6 +610,7 @@ func findWorkspaceSkillByDirectory(cfg *config.Config, directory string) *skillS
 
 func findWorkspaceSkillInfoByDirectory(workspace, directory string) *skills.SkillInfo {
 	loader := skills.NewSkillsLoader(workspace, "", "", "", nil, false)
+
 	for _, skill := range loader.ListSkills() {
 		if skill.Source != "workspace" {
 			continue

From d37d6e6871315a6e93201d7129acc5712f4fd474 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Thu, 2 Apr 2026 08:15:29 +0200
Subject: [PATCH 23/25] chore: fixes for userAgent support and host detection
 after rebase stabilization

---
 pkg/providers/factory_provider.go | 1 +
 pkg/providers/http_provider.go    | 7 ++++---
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index 60311ba18..e3b15297e 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -269,6 +269,7 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 			cfg.APIKey(),
 			cfg.APIBase,
 			cfg.Proxy,
+			userAgent,
 			cfg.RequestTimeout,
 		), modelID, nil
 
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index 0e197d754..2e97bd8f2 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -17,9 +17,9 @@ type HTTPProvider struct {
 	delegate *openai_compat.Provider
 }
 
-func NewHTTPProvider(apiKey, apiBase, proxy string) *HTTPProvider {
+func NewHTTPProvider(apiKey, apiBase, proxy, userAgent string) *HTTPProvider {
 	return &HTTPProvider{
-		delegate: openai_compat.NewProvider(apiKey, apiBase, proxy),
+		delegate: openai_compat.NewProvider(apiKey, apiBase, proxy, openai_compat.WithUserAgent(userAgent)),
 	}
 }
 
@@ -45,7 +45,7 @@ func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
 	}
 }
 
-func NewAzureAIProvider(apiKey, apiBase, proxy string, requestTimeoutSeconds int) *HTTPProvider {
+func NewAzureAIProvider(apiKey, apiBase, proxy, userAgent string, requestTimeoutSeconds int) *HTTPProvider {
 	return &HTTPProvider{
 		delegate: openai_compat.NewProvider(
 			apiKey,
@@ -53,6 +53,7 @@ func NewAzureAIProvider(apiKey, apiBase, proxy string, requestTimeoutSeconds int
 			proxy,
 			openai_compat.WithAzureHeaders(true),
 			openai_compat.WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+			openai_compat.WithUserAgent(userAgent),
 		),
 	}
 }

From d903381f66a9df5c22256590d83384d1f67b4fd0 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Fri, 3 Apr 2026 15:00:11 +0200
Subject: [PATCH 24/25] chore: remove n8n-test MCP server from k3s
 configuration

---
 k3s/configmap.yaml | 16 ++++------------
 1 file changed, 4 insertions(+), 12 deletions(-)

diff --git a/k3s/configmap.yaml b/k3s/configmap.yaml
index c8567c647..11719ef49 100644
--- a/k3s/configmap.yaml
+++ b/k3s/configmap.yaml
@@ -16,7 +16,7 @@ data:
           "restrict_to_workspace": true,
           "allow_read_outside_workspace": false,
           "provider": "",
-          "model_name": "nemotron-3-super-120b-a12b",
+          "model_name": "gemini-2.0-flash",
           "max_tokens": 32768,
           "max_tool_iterations": 50,
           "summarize_message_threshold": 20,
@@ -254,7 +254,8 @@ data:
         {
           "model_name": "gemini-2.0-flash",
           "model": "gemini/gemini-2.0-flash-exp",
-          "api_base": "https://generativelanguage.googleapis.com/v1beta"
+          "api_base": "https://generativelanguage.googleapis.com/v1beta",
+          "api_key": "file://secrets/google-api-key"
         },
         {
           "model_name": "qwen-plus",
@@ -506,14 +507,6 @@ data:
               "command": "",
               "type": "sse",
               "url": "http://hdn-server:8080/mcp"
-            },
-            "n8n-test": {
-              "enabled": true,
-              "type": "sse",
-              "url": "https://n8namber.app.n8n.cloud/mcp/a5747ff8-db9b-4326-8bef-474301f65251",
-              "headers": {
-                "Authorization": "Bearer 97340696-89AE-43B2-B6E2-080E062150C9"
-              }
             }
           }
         },
@@ -530,8 +523,7 @@ data:
           "weather",
           "summarize",
           "github",
-          "hdn-server",
-          "n8n-test"
+          "hdn-server"
         ],
         "whitelist_enabled": true,
         "append_file": {

From 268377b99eafa2fc6f9e283dc3dc0548a7bfec28 Mon Sep 17 00:00:00 2001
From: stevef <stevef@omen.home>
Date: Fri, 3 Apr 2026 17:28:55 +0200
Subject: [PATCH 25/25] chore: restore stable Gemini configuration for k3s
 deployment

---
 k3s/configmap.yaml | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/k3s/configmap.yaml b/k3s/configmap.yaml
index 11719ef49..515862e1c 100644
--- a/k3s/configmap.yaml
+++ b/k3s/configmap.yaml
@@ -16,7 +16,7 @@ data:
           "restrict_to_workspace": true,
           "allow_read_outside_workspace": false,
           "provider": "",
-          "model_name": "gemini-2.0-flash",
+          "model_name": "gemini-flash",
           "max_tokens": 32768,
           "max_tool_iterations": 50,
           "summarize_message_threshold": 20,
@@ -252,10 +252,11 @@ data:
           "api_base": "https://api.deepseek.com/v1"
         },
         {
-          "model_name": "gemini-2.0-flash",
-          "model": "gemini/gemini-2.0-flash-exp",
-          "api_base": "https://generativelanguage.googleapis.com/v1beta",
-          "api_key": "file://secrets/google-api-key"
+          "model_name": "gemini-flash",
+          "model": "openai/gemini-1.5-flash",
+          "api_base": "https://generativelanguage.googleapis.com/v1beta/openai/",
+          "api_key": "env://GOOGLE_API_KEY",
+          "request_timeout": 300
         },
         {
           "model_name": "qwen-plus",