feat(tools): scope file reads to workspace

Author: lucasnevespereira

README.md

@@ -69,6 +69,8 @@ vikusha create writer
 vikusha chat writer
 ```
 
+Named agents get their own `workspace/`. Built-in file tools read from that workspace and reject paths outside it.
+
 You can load the same YAML from Go.
 
 ```go

cmd/vikusha/main.go

@@ -184,7 +184,17 @@ func buildAgent(input string) (*agent.Agent, error) {
 	if err != nil {
 		return nil, err
 	}
-	return vikusha.LoadAgent(path, vikusha.Options{})
+	return vikusha.LoadAgent(path, vikusha.Options{
+		Workspace: workspaceForCharacter(path),
+	})
+}
+
+func workspaceForCharacter(path string) string {
+	workspace := filepath.Join(filepath.Dir(path), "workspace")
+	if fileExists(workspace) {
+		return workspace
+	}
+	return ""
 }
 
 func resolveCharacterPath(input string) (string, error) {

cmd/vikusha/main_test.go

@@ -160,3 +160,23 @@ func TestResolveCharacterPathReportsMissingNamedAgent(t *testing.T) {
 		t.Fatalf("expected agent path in error, got %q", err.Error())
 	}
 }
+
+func TestWorkspaceForCharacterUsesSiblingWorkspace(t *testing.T) {
+	dir := t.TempDir()
+	workspace := filepath.Join(dir, "workspace")
+	if err := os.Mkdir(workspace, 0o700); err != nil {
+		t.Fatal(err)
+	}
+
+	got := workspaceForCharacter(filepath.Join(dir, "character.yaml"))
+	if got != workspace {
+		t.Fatalf("workspaceForCharacter() = %q, want %q", got, workspace)
+	}
+}
+
+func TestWorkspaceForCharacterReturnsEmptyWhenMissing(t *testing.T) {
+	got := workspaceForCharacter(filepath.Join(t.TempDir(), "character.yaml"))
+	if got != "" {
+		t.Fatalf("workspaceForCharacter() = %q, want empty", got)
+	}
+}

core/tools/file/read.go

@@ -5,11 +5,21 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"path/filepath"
+	"strings"
 )
 
-type Read struct{}
+type Read struct {
+	root string
+}
 
-func NewRead() *Read { return &Read{} }
+func NewRead(root ...string) *Read {
+	r := &Read{}
+	if len(root) > 0 {
+		r.root = strings.TrimSpace(root[0])
+	}
+	return r
+}
 
 func (r *Read) Name() string { return "file_read" }
 
@@ -42,9 +52,45 @@ func (r *Read) Run(ctx context.Context, input json.RawMessage) (string, error) {
 	if in.Path == "" {
 		return "", fmt.Errorf("invalid input: path is required")
 	}
-	data, err := os.ReadFile(in.Path)
+	path, err := r.resolve(in.Path)
+	if err != nil {
+		return "", err
+	}
+	data, err := os.ReadFile(path)
 	if err != nil {
 		return "", err
 	}
 	return string(data), nil
 }
+
+func (r *Read) resolve(path string) (string, error) {
+	if r.root == "" {
+		return path, nil
+	}
+
+	root, err := filepath.Abs(r.root)
+	if err != nil {
+		return "", err
+	}
+	root, err = filepath.EvalSymlinks(root)
+	if err != nil {
+		return "", err
+	}
+
+	target := path
+	if !filepath.IsAbs(target) {
+		target = filepath.Join(root, target)
+	}
+	target, err = filepath.Abs(target)
+	if err != nil {
+		return "", err
+	}
+	target, err = filepath.EvalSymlinks(target)
+	if err != nil {
+		return "", err
+	}
+	if target != root && !strings.HasPrefix(target, root+string(os.PathSeparator)) {
+		return "", fmt.Errorf("path %q is outside workspace %q", path, root)
+	}
+	return target, nil
+}

core/tools/file/read_test.go

@@ -0,0 +1,97 @@
+package file
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestReadUnscopedReadsPath(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "note.txt")
+	if err := os.WriteFile(path, []byte("hello"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := NewRead().Run(context.Background(), readJSON(path))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "hello" {
+		t.Fatalf("Run() = %q, want hello", got)
+	}
+}
+
+func TestReadScopedReadsRelativePathFromWorkspace(t *testing.T) {
+	workspace := t.TempDir()
+	if err := os.WriteFile(filepath.Join(workspace, "note.txt"), []byte("hello"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := NewRead(workspace).Run(context.Background(), readJSON("note.txt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "hello" {
+		t.Fatalf("Run() = %q, want hello", got)
+	}
+}
+
+func TestReadScopedRejectsParentEscape(t *testing.T) {
+	base := t.TempDir()
+	workspace := filepath.Join(base, "workspace")
+	if err := os.Mkdir(workspace, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(base, "secret.txt"), []byte("secret"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := NewRead(workspace).Run(context.Background(), readJSON("../secret.txt"))
+	if err == nil {
+		t.Fatal("expected workspace escape error")
+	}
+	if !strings.Contains(err.Error(), "outside workspace") {
+		t.Fatalf("error = %q, want outside workspace", err)
+	}
+}
+
+func TestReadScopedRejectsAbsolutePathOutsideWorkspace(t *testing.T) {
+	workspace := t.TempDir()
+	outside := filepath.Join(t.TempDir(), "secret.txt")
+	if err := os.WriteFile(outside, []byte("secret"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := NewRead(workspace).Run(context.Background(), readJSON(outside))
+	if err == nil {
+		t.Fatal("expected workspace escape error")
+	}
+}
+
+func TestReadScopedRejectsSymlinkEscape(t *testing.T) {
+	base := t.TempDir()
+	workspace := filepath.Join(base, "workspace")
+	if err := os.Mkdir(workspace, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	secret := filepath.Join(base, "secret.txt")
+	if err := os.WriteFile(secret, []byte("secret"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(secret, filepath.Join(workspace, "secret-link")); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := NewRead(workspace).Run(context.Background(), readJSON("secret-link"))
+	if err == nil {
+		t.Fatal("expected workspace escape error")
+	}
+}
+
+func readJSON(path string) json.RawMessage {
+	data, _ := json.Marshal(readInput{Path: path})
+	return data
+}

docs/ROADMAP.md

@@ -64,9 +64,9 @@ A single agent you can talk to from the terminal, backed by a core harness that
 
 - [x] Each agent owns `~/.vikusha/agents/<name>/` with its own character, memory directory, and workspace directory.
 - [ ] Per-agent logs under `~/.vikusha/agents/<name>/logs`.
-- [ ] File tools default-scoped to the agent's workspace.
+- [x] File tools default-scoped to the agent's workspace.
 - [ ] Paths outside the workspace require explicit approval, persisted per agent.
-- [ ] Path resolution blocks `..` escapes and symlinks pointing outside the workspace.
+- [x] Path resolution blocks `..` escapes and symlinks pointing outside the workspace.
 
 ### Tools
 

vikusha.go

@@ -15,8 +15,9 @@ import (
 )
 
 type Options struct {
-	Env   func(string) string
-	Tools map[string]tool.Tool
+	Env       func(string) string
+	Tools     map[string]tool.Tool
+	Workspace string
 }
 
 func LoadAgent(path string, opts Options) (*agent.Agent, error) {
@@ -93,7 +94,7 @@ func buildMemory(c *character.Character) (memory.Memory, error) {
 func registry(names []string, opts Options) (*tool.Registry, error) {
 	reg := tool.NewRegistry()
 	available := map[string]tool.Tool{
-		"file_read": file.NewRead(),
+		"file_read": file.NewRead(opts.Workspace),
 	}
 	for name, t := range opts.Tools {
 		available[name] = t

vikusha_test.go

@@ -1,6 +1,8 @@
 package vikusha
 
 import (
+	"context"
+	"encoding/json"
 	"os"
 	"path/filepath"
 	"strings"
@@ -62,3 +64,46 @@ memory:
 		t.Fatalf("error = %q, want memory.path", err)
 	}
 }
+
+func TestRegistryScopesBuiltInFileReadToWorkspace(t *testing.T) {
+	base := t.TempDir()
+	workspace := filepath.Join(base, "workspace")
+	if err := os.Mkdir(workspace, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(workspace, "note.txt"), []byte("inside"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(base, "secret.txt"), []byte("outside"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	reg, err := registry([]string{"file_read"}, Options{Workspace: workspace})
+	if err != nil {
+		t.Fatal(err)
+	}
+	read, ok := reg.Get("file_read")
+	if !ok {
+		t.Fatal("file_read not registered")
+	}
+
+	got, err := read.Run(context.Background(), mustJSON(t, map[string]string{"path": "note.txt"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != "inside" {
+		t.Fatalf("file_read = %q, want inside", got)
+	}
+	if _, err := read.Run(context.Background(), mustJSON(t, map[string]string{"path": "../secret.txt"})); err == nil {
+		t.Fatal("expected workspace escape error")
+	}
+}
+
+func mustJSON(t *testing.T, v any) json.RawMessage {
+	t.Helper()
+	data, err := json.Marshal(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return data
+}