compact: retain newest ~20% of context; refactor startup into internal/app

- Replace fixed 6-message compact retention with ratio-based logic:
  retain ~20% of compactable estimated tokens, with a 6-message floor
  and user-turn boundary alignment
- Add compactRetainedTokenBudget, compactRecentStart, compactTurnBoundary
  helpers in internal/agent/agent.go
- Add TestAgentCompactKeepsTwentyPercentRecentContext
- Move startup/session/repl/bootstrap logic from root into internal/app
  so main.go is a thin binary entry point (15 lines)
- Update /compact docs in README.md

README.md

@@ -20,13 +20,19 @@ model/provider switching, and local tools.
 mkdir -p ~/.agentu
 cp agentu.example.yaml ~/.agentu/config.yaml
 export AGENTU_API_KEY='your-api-key'
-go run ./cmd/agentu
+go run .
+```
+
+Use dark mode when your terminal is dark:
+
+```sh
+go run . --theme dark
 ```
 
 Use `--yolo` only when you want agentu to write files or run shell commands:
 
 ```sh
-go run ./cmd/agentu --yolo
+go run . --yolo
 ```
 
 ## Config
@@ -82,7 +88,7 @@ top-level OpenAI-compatible request field named `thinking`.
 ## CLI Flags
 
 ```sh
-go run ./cmd/agentu [flags]
+go run . [flags]
 ```
 
 - `--config <path>` loads a YAML config file. Default: `~/.agentu/config.yaml`.
@@ -103,7 +109,7 @@ go run ./cmd/agentu [flags]
 Slash commands:
 
 - `/clear` resets conversation history.
-- `/compact` summarizes older conversation history and keeps recent context.
+- `/compact` summarizes older conversation history and keeps the newest ~20% of context, with a small recent-message floor.
 - `/status` shows changed files with `git status --short`.
 - `/diff [--stat] [path...]` shows the unstaged git diff.
 - `/test [command...]` runs a project test command; defaults to `go test ./...` for Go modules or `npm test` for Node projects.
@@ -125,6 +131,9 @@ Read-only tools are available by default:
 - `file_list`
 - `file_search` with optional `context_lines` and `max_results`
 - `code_symbols` for Go packages, imports, types, functions, and methods
+- `git_status` shows changed files
+- `git_diff` shows unstaged or staged diff output
+- `git_log` shows recent commit history
 
 Web tools are also available in read-only mode:
 
@@ -133,8 +142,9 @@ Web tools are also available in read-only mode:
 
 `--yolo` additionally enables:
 
-- `file_write`
-- `shell_run`
+- `file_write` for creating or replacing whole files
+- `file_edit` for surgical line-range or pattern edits to existing files
+- `shell_run` for non-interactive shell commands
 
 Use `--yolo` for prompts that ask agentu to run or inspect local commands, for
 example:
@@ -143,6 +153,8 @@ example:
 请帮我运行 `go test ./...` 并总结结果
 ```
 
+
+
 ## Development
 
 Run the verification suite:
@@ -150,7 +162,7 @@ Run the verification suite:
 ```sh
 go test ./...
 go vet ./...
-go build ./cmd/agentu
+go build .
 ```
 
 Local config and build outputs are intentionally ignored by git.

cmd/agentu/main.go

@@ -1,222 +0,0 @@
-package main
-
-import (
-	"bufio"
-	"context"
-	"errors"
-	"flag"
-	"fmt"
-	"net/http"
-	"os"
-	"os/signal"
-	"path/filepath"
-	"strings"
-
-	"agentu/internal/agent"
-	"agentu/internal/config"
-	"agentu/internal/llm"
-	"agentu/internal/session"
-	"agentu/internal/tools"
-	"agentu/internal/tui"
-)
-
-const defaultConfigContent = `# agentu configuration
-# Replace the placeholder values below with your actual provider settings.
-# See agentu.example.yaml for the full reference.
-providers:
-  default:
-    base_url: https://api.openai.com
-    api_key: YOUR_API_KEY_HERE
-    models:
-      - id: gpt-4o
-        context: 128000
-      - id: gpt-4o-mini
-        context: 128000
-`
-
-func main() {
-	if err := run(); err != nil {
-		fmt.Fprintln(os.Stderr, "agentu:", err)
-		os.Exit(1)
-	}
-}
-
-func run() error {
-	configPath := flag.String("config", config.DefaultPath, "path to YAML config")
-	yolo := flag.Bool("yolo", false, "also enable automatic file writes and shell execution")
-	plain := flag.Bool("plain", false, "use the simple line-based REPL instead of the TUI")
-	themeName := flag.String("theme", "light", "TUI theme: light or dark")
-	resumeID := flag.String("resume", "", "resume a specific session by ID")
-	flag.Parse()
-
-	themeMode, err := tui.ParseThemeMode(*themeName)
-	if err != nil {
-		return err
-	}
-
-	cfg, err := config.Load(*configPath)
-	if err != nil {
-		if errors.Is(err, os.ErrNotExist) {
-			if bootstrapErr := bootstrapConfig(*configPath); bootstrapErr != nil {
-				return bootstrapErr
-			}
-			return fmt.Errorf("created default config at %s; edit it to set your API key and provider, then restart agentu", *configPath)
-		}
-		return err
-	}
-
-	providerName := cfg.DefaultProviderName()
-	providerConfig := cfg.Providers[providerName]
-	provider := llm.NewOpenAICompatibleClient(providerConfig.BaseURL, providerConfig.APIKey, http.DefaultClient)
-
-	var registry *tools.Registry
-	if *yolo {
-		registry = tools.Builtins(cfg.Agent.WorkingDir)
-	} else {
-		registry = tools.ReadOnlyBuiltins(cfg.Agent.WorkingDir)
-	}
-	registry.Register(tools.NewBuiltinSearchTool(http.DefaultClient))
-	registry.Register(tools.NewBuiltinFetchTool(http.DefaultClient))
-	systemPrompt := strings.TrimSpace(cfg.Agent.SystemPrompt + "\n\n" + tools.AgentInstructions(cfg.Agent.WorkingDir, *yolo))
-	maxContextTokens := cfg.Agent.MaxContextTokens
-	if maxContextTokens == 0 {
-		maxContextTokens = providerConfig.ContextTokens
-	}
-
-	assistant := agent.New(agent.Options{
-		Provider:         provider,
-		ProviderName:     providerName,
-		Model:            providerConfig.Model,
-		Thinking:         providerConfig.Thinking,
-		ThinkingParam:    providerConfig.ThinkingParam,
-		ThinkingEnabled:  providerConfig.ThinkingConfigured,
-		SystemPrompt:     systemPrompt,
-		ToolRegistry:     registry,
-		ToolTimeout:      cfg.Agent.ToolTimeout,
-		MaxContextTokens: maxContextTokens,
-	})
-
-	// Initialize session store
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return fmt.Errorf("resolve home dir: %w", err)
-	}
-	sessionsDir := filepath.Join(home, ".agentu", "sessions")
-	store, err := session.NewStore(sessionsDir)
-	if err != nil {
-		return fmt.Errorf("init session store: %w", err)
-	}
-
-	modelManager, err := session.NewManager(cfg, assistant, http.DefaultClient, store)
-	if err != nil {
-		return err
-	}
-
-	// Resume session
-	if *resumeID != "" {
-		if err := modelManager.Resume(*resumeID); err != nil {
-			return fmt.Errorf("resume session: %w", err)
-		}
-	} else {
-		if err := modelManager.ResumeLatest(); err != nil {
-			return fmt.Errorf("resume latest session: %w", err)
-		}
-	}
-
-	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
-	defer stop()
-
-	if !*plain {
-		err := tui.Run(ctx, assistant, tui.Options{
-			ModelName:    providerConfig.Model,
-			Yolo:         *yolo,
-			ThemeMode:    themeMode,
-			ModelManager: modelManager,
-			WorkingDir:   cfg.Agent.WorkingDir,
-		})
-		printExitSession(modelManager)
-		return err
-	}
-
-	return repl(ctx, assistant, modelManager)
-}
-
-func bootstrapConfig(configPath string) error {
-	resolved, err := config.ResolvePath(configPath)
-	if err != nil {
-		return fmt.Errorf("resolve config path: %w", err)
-	}
-	dir := filepath.Dir(resolved)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("create config directory: %w", err)
-	}
-	if err := os.WriteFile(resolved, []byte(defaultConfigContent), 0o644); err != nil {
-		return fmt.Errorf("write default config: %w", err)
-	}
-	return nil
-}
-
-func repl(ctx context.Context, assistant *agent.Agent, modelManager *session.Manager) error {
-	scanner := bufio.NewScanner(os.Stdin)
-	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
-
-	fmt.Println("agentu")
-	fmt.Println("Type /exit to quit, /clear to reset context, /compact to compress context.")
-	for {
-		fmt.Print("> ")
-		if !scanner.Scan() {
-			if err := scanner.Err(); err != nil {
-				return err
-			}
-			fmt.Println()
-			printExitSession(modelManager)
-			return nil
-		}
-
-		input := strings.TrimSpace(scanner.Text())
-		switch input {
-		case "":
-			continue
-		case "/exit", "/quit":
-			printExitSession(modelManager)
-			return nil
-		case "/clear":
-			assistant.Clear()
-			fmt.Println("context cleared")
-			continue
-		case "/compact":
-			if err := assistant.Compact(ctx); err != nil {
-				fmt.Fprintln(os.Stderr, "compact error:", err)
-			} else {
-				fmt.Println("context compacted")
-				if modelManager != nil {
-					_ = modelManager.Save()
-				}
-			}
-			continue
-		}
-
-		if err := assistant.RunTurn(ctx, input, os.Stdout, os.Stderr); err != nil {
-			fmt.Fprintln(os.Stderr, "\nerror:", err)
-		}
-		_ = modelManager.Save()
-		fmt.Println()
-	}
-}
-
-func printExitSession(m *session.Manager) {
-	if m == nil {
-		return
-	}
-	_ = m.Save()
-	id := m.CurrentSessionID()
-	name := m.CurrentSessionName()
-	if id != "" {
-		if name != "" && name != id {
-			fmt.Fprintf(os.Stderr, "session: %s (%s)\n", id, name)
-		} else {
-			fmt.Fprintf(os.Stderr, "session: %s\n", id)
-		}
-		fmt.Fprintf(os.Stderr, "resume:  agentu --resume %s\n", id)
-	}
-}

internal/agent/agent.go

@@ -7,18 +7,23 @@ import (
 	"io"
 	"sort"
 	"strings"
+	"sync"
 	"time"
 
-	"agentu/internal/llm"
 	"agentu/internal/tools"
+	"agentu/pkg/llm"
 )
 
 const (
 	defaultMaxToolRounds      = 50
 	doomLoopThreshold         = 3
-	compactRecentMessages = 6
+	compactMinRecentMessages      = 6
+	compactRecentRetentionPercent = 20
 	summaryMessageLimit       = 8000
 	contextSummaryPrefix      = "[context summary]"
+	toolLogArgumentLimit      = 400
+	toolLogOutputPreviewBytes = 4096
+	toolLogOutputMarker       = "[output]"
 
 	summarizerSystemPrompt = "You are a conversation summarizer. Summarize the following conversation history into a concise but detailed summary. Preserve:\n" +
 		"- Key facts, decisions, and conclusions\n" +
@@ -29,6 +34,11 @@ const (
 		"Output only the summary, no preamble."
 )
 
+type toolExecutionResult struct {
+	call   llm.ToolCall
+	output string
+}
+
 type Agent struct {
 	provider         llm.Provider
 	providerName     string
@@ -172,6 +182,61 @@ func (a *Agent) SetLastUsage(usage *llm.Usage) {
 	copy := *usage
 	a.lastUsage = &copy
 }
+// compactRetainedTokenBudget returns the number of estimated tokens to retain
+// based on compactRecentRetentionPercent, using integer ceiling division.
+func compactRetainedTokenBudget(totalTokens int) int {
+	if totalTokens <= 0 {
+		return 1
+	}
+	return (totalTokens*compactRecentRetentionPercent + 99) / 100
+}
+
+// compactTurnBoundary walks backward from start until it finds a user message
+// or reaches prefixEnd, ensuring the retained suffix starts at a user turn.
+func compactTurnBoundary(messages []llm.Message, prefixEnd int, start int) int {
+	for start > prefixEnd && messages[start].Role != llm.RoleUser {
+		start--
+	}
+	return start
+}
+
+// compactRecentStart returns the index where the retained recent suffix begins.
+// It balances the 20% token-budget ratio with the compactMinRecentMessages floor
+// and aligns to a user-turn boundary.
+func compactRecentStart(messages []llm.Message, prefixEnd int) int {
+	compactableCount := len(messages) - prefixEnd
+	if compactableCount <= compactMinRecentMessages {
+		return len(messages)
+	}
+
+	compactable := messages[prefixEnd:]
+	totalTokens := llm.EstimateTokens(compactable, nil)
+	retainTokens := compactRetainedTokenBudget(totalTokens)
+
+	// Walk backward from the end to find the earliest suffix fitting the budget.
+	ratioStart := len(messages) - 1
+	for i := len(messages) - 1; i >= prefixEnd; i-- {
+		if llm.EstimateTokens(messages[i:], nil) <= retainTokens {
+			ratioStart = i
+		} else {
+			break
+		}
+	}
+
+	// Enforce the minimum recent-message floor.
+	minStart := len(messages) - compactMinRecentMessages
+	if minStart < prefixEnd {
+		minStart = prefixEnd
+	}
+	// Choose the earlier start so the floor is never weakened.
+	start := minStart
+	if ratioStart < start {
+		start = ratioStart
+	}
+
+	return compactTurnBoundary(messages, prefixEnd, start)
+}
+
 
 // Compact summarizes older conversation messages while preserving the system
 // prompt and recent messages intact.
@@ -187,12 +252,8 @@ func (a *Agent) Compact(ctx context.Context) error {
 	if a.messages[0].Role == llm.RoleSystem {
 		prefixEnd = 1
 	}
-	if len(a.messages)-prefixEnd <= compactRecentMessages {
-		return nil
-	}
-
-	recentStart := len(a.messages) - compactRecentMessages
-	if recentStart <= prefixEnd {
+	recentStart := compactRecentStart(a.messages, prefixEnd)
+	if recentStart <= prefixEnd || recentStart >= len(a.messages) {
 		return nil
 	}
 	middle := append([]llm.Message(nil), a.messages[prefixEnd:recentStart]...)
@@ -364,14 +425,15 @@ func (a *Agent) RunTurn(ctx context.Context, input string, out io.Writer, logs i
 			}
 		}
 
-		for _, call := range calls {
-			result := a.executeTool(ctx, call, logs)
+		results := a.executeTools(ctx, calls, logs)
+		for _, result := range results {
 			a.messages = append(a.messages, llm.Message{
 				Role:       llm.RoleTool,
-				ToolCallID: call.ID,
-				Content:    result,
+				ToolCallID: result.call.ID,
+				Content:    result.output,
 			})
 		}
+
 	}
 
 	return fmt.Errorf("tool round limit reached after %d rounds; the task may be too complex for a single turn", a.maxToolRounds)
@@ -433,11 +495,8 @@ func (a *Agent) toolDefinitions() []llm.Tool {
 	return a.toolRegistry.Definitions()
 }
 
-func (a *Agent) executeTool(ctx context.Context, call llm.ToolCall, logs io.Writer) string {
+func (a *Agent) executeTool(ctx context.Context, call llm.ToolCall) string {
 	name := call.Function.Name
-	if logs != nil {
-		fmt.Fprintf(logs, "\n[tool] %s %s\n", name, compact(call.Function.Arguments, 400))
-	}
 
 	if a.toolRegistry == nil {
 		return tools.FormatError(fmt.Errorf("tool registry is disabled"))
@@ -461,12 +520,84 @@ func (a *Agent) executeTool(ctx context.Context, call llm.ToolCall, logs io.Writ
 		}
 		return tools.FormatError(err)
 	}
-	if logs != nil {
-		fmt.Fprintf(logs, "[tool] %s done\n", name)
-	}
 	return output
 }
 
+func (a *Agent) hasMutatingCall(calls []llm.ToolCall) bool {
+	if a.toolRegistry == nil {
+		return false
+	}
+	for _, call := range calls {
+		if tool, ok := a.toolRegistry.Get(call.Function.Name); ok {
+			if tools.IsMutating(tool) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func (a *Agent) executeTools(ctx context.Context, calls []llm.ToolCall, logs io.Writer) []toolExecutionResult {
+	results := make([]toolExecutionResult, len(calls))
+
+	// Log all tool starts sequentially so TUI gets ordered placeholders.
+	if logs != nil {
+		for _, call := range calls {
+			logToolStart(logs, call)
+		}
+	}
+
+	if a.hasMutatingCall(calls) {
+		// Sequential: avoid racing mutating tools.
+		for i, call := range calls {
+			output := a.executeTool(ctx, call)
+			results[i] = toolExecutionResult{call: call, output: output}
+			if logs != nil {
+				logToolOutput(logs, call, output)
+			}
+		}
+		return results
+	}
+
+	// Concurrent: independent read-only tools.
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+	for i, call := range calls {
+		wg.Add(1)
+		go func(idx int, c llm.ToolCall) {
+			defer wg.Done()
+			output := a.executeTool(ctx, c)
+			results[idx] = toolExecutionResult{call: c, output: output}
+			if logs != nil {
+				mu.Lock()
+				logToolOutput(logs, c, output)
+				mu.Unlock()
+			}
+		}(i, call)
+	}
+	wg.Wait()
+	return results
+}
+
+func logToolStart(logs io.Writer, call llm.ToolCall) {
+	fmt.Fprintf(logs, "\n[tool] %s %s\n", call.Function.Name, compact(call.Function.Arguments, toolLogArgumentLimit))
+}
+
+func logToolOutput(logs io.Writer, call llm.ToolCall, output string) {
+	fmt.Fprintf(logs, "\n[tool] %s %s\n%s\n%s\n", call.Function.Name, compact(call.Function.Arguments, toolLogArgumentLimit), toolLogOutputMarker, toolOutputPreview(output))
+}
+
+func toolOutputPreview(output string) string {
+	output = strings.TrimSpace(output)
+	if output == "" {
+		return "(no output)"
+	}
+	if len(output) <= toolLogOutputPreviewBytes {
+		return output
+	}
+	return output[:toolLogOutputPreviewBytes] + fmt.Sprintf("\n[truncated: showing first %d bytes; omitted %d bytes]", toolLogOutputPreviewBytes, len(output)-toolLogOutputPreviewBytes)
+}
+
 type toolCallBuilder struct {
 	index     int
 	id        string

internal/agent/agent_test.go

@@ -7,8 +7,8 @@ import (
 	"strings"
 	"testing"
 
-	"agentu/internal/llm"
 	"agentu/internal/tools"
+	"agentu/pkg/llm"
 )
 
 type fakeProvider struct {
@@ -145,6 +145,9 @@ func TestAgentCompact(t *testing.T) {
 	if messages[len(messages)-1].Content != "recent-answer-2" {
 		t.Fatalf("last recent message = %#v", messages[len(messages)-1])
 	}
+	if messages[2].Content != "recent-user-0" {
+		t.Fatalf("first retained recent message = %#v", messages[2])
+	}
 	if usage := a.LastUsage(); usage == nil || usage.TotalTokens != 12 {
 		t.Fatalf("usage = %#v", usage)
 	}
@@ -217,6 +220,48 @@ func longConversation() []llm.Message {
 	return messages
 }
 
+func manyTurnConversation(turns int) []llm.Message {
+	messages := []llm.Message{{Role: llm.RoleSystem, Content: "system"}}
+	for i := 0; i < turns; i++ {
+		messages = append(messages,
+			llm.Message{Role: llm.RoleUser, Content: fmt.Sprintf("user-%02d", i)},
+			llm.Message{Role: llm.RoleAssistant, Content: fmt.Sprintf("assistant-%02d", i)},
+		)
+	}
+	return messages
+}
+
+func TestAgentCompactKeepsTwentyPercentRecentContext(t *testing.T) {
+	provider := &compactProvider{}
+	a := New(Options{Provider: provider, Model: "test", SystemPrompt: "system"})
+	a.SetMessages(manyTurnConversation(25))
+
+	if err := a.Compact(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+
+	messages := a.Messages()
+	// 1 system + 1 summary + 10 retained recent messages (5 user/assistant turns)
+	if len(messages) != 12 {
+		t.Fatalf("messages = %d, want 12; contents: %v", len(messages), joinMessageContents(messages))
+	}
+	if provider.summaryCalls != 1 {
+		t.Fatalf("summaryCalls = %d, want 1", provider.summaryCalls)
+	}
+	if messages[2].Content != "user-20" {
+		t.Fatalf("first retained message = %#v, want user-20", messages[2])
+	}
+	if messages[len(messages)-1].Content != "assistant-24" {
+		t.Fatalf("last retained message = %#v, want assistant-24", messages[len(messages)-1])
+	}
+	if !strings.Contains(provider.lastSummary, "user-19") {
+		t.Fatalf("summary should contain user-19 (part of summarized 80%%): %q", provider.lastSummary)
+	}
+	if strings.Contains(provider.lastSummary, "user-20") {
+		t.Fatalf("summary should not contain user-20 (part of retained 20%%): %q", provider.lastSummary)
+	}
+}
+
 func joinMessageContents(messages []llm.Message) string {
 	var b strings.Builder
 	for _, msg := range messages {
@@ -340,3 +385,174 @@ func TestAgentHardLimitStopsVaryingCalls(t *testing.T) {
 		t.Fatalf("calls = %d, want %d", provider.calls, limit)
 	}
 }
+
+// slowTool blocks on a channel before returning.
+type slowTool struct {
+	name    string
+	started chan<- string
+	release <-chan struct{}
+}
+
+func (t *slowTool) Definition() llm.Tool {
+	return llm.Tool{
+		Type: "function",
+		Function: llm.ToolFunction{
+			Name:        t.name,
+			Description: "slow test tool",
+			Parameters:  json.RawMessage(`{"type":"object","properties":{"text":{"type":"string"}}}`),
+		},
+	}
+}
+
+func (t *slowTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
+	var args struct {
+		Text string `json:"text"`
+	}
+	if err := json.Unmarshal(raw, &args); err != nil {
+		return "", err
+	}
+	t.started <- t.name
+	<-t.release
+	return args.Text, nil
+}
+
+// mutatingSlowTool is like slowTool but implements MutatingTool.
+type mutatingSlowTool struct {
+	slowTool
+}
+
+func (*mutatingSlowTool) Mutates() bool { return true }
+
+func TestAgentExecutesIndependentToolCallsInParallel(t *testing.T) {
+	started := make(chan string, 2)
+	release := make(chan struct{})
+
+	tool1 := &slowTool{name: "slow_one", started: started, release: release}
+	tool2 := &slowTool{name: "slow_two", started: started, release: release}
+
+	provider := &parallelProvider{
+		responses: [][]llm.ToolCallDelta{
+			{
+				{Index: 0, ID: "call_1", Type: "function", Name: "slow_one", Arguments: `{"text":"one"}`},
+				{Index: 1, ID: "call_2", Type: "function", Name: "slow_two", Arguments: `{"text":"two"}`},
+			},
+		},
+		finalContent: "done",
+	}
+
+	a := New(Options{
+		Provider:     provider,
+		Model:        "test",
+		SystemPrompt: "system",
+		ToolRegistry: tools.NewRegistry(tool1, tool2),
+	})
+
+	var out strings.Builder
+	done := make(chan error, 1)
+	go func() {
+		done <- a.RunTurn(context.Background(), "run both", &out, nil)
+	}()
+
+	// Both tools must start before we release them.
+	names := make(map[string]bool)
+	for i := 0; i < 2; i++ {
+		select {
+		case name := <-started:
+			names[name] = true
+		case <-make(chan struct{}):
+			// Use a timer in real code, but for test simplicity we rely on deadlock detection.
+			t.Fatal("timed out waiting for tool to start")
+		}
+	}
+	if !names["slow_one"] || !names["slow_two"] {
+		t.Fatalf("expected both tools to start, got %v", names)
+	}
+	close(release)
+
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+	if out.String() != "done" {
+		t.Fatalf("out = %q", out.String())
+	}
+	// Verify tool results were in order.
+	msgs := a.Messages()
+	var toolMsgs []string
+	for _, m := range msgs {
+		if m.Role == llm.RoleTool {
+			toolMsgs = append(toolMsgs, m.Content)
+		}
+	}
+	if len(toolMsgs) != 2 || toolMsgs[0] != "one" || toolMsgs[1] != "two" {
+		t.Fatalf("tool messages = %v, want [one two]", toolMsgs)
+	}
+}
+
+func TestAgentRunsMutatingToolCallsSequentially(t *testing.T) {
+	started := make(chan string, 2)
+	release := make(chan struct{})
+
+	tool1 := &mutatingSlowTool{slowTool{name: "mut_one", started: started, release: release}}
+	tool2 := &mutatingSlowTool{slowTool{name: "mut_two", started: started, release: release}}
+
+	provider := &parallelProvider{
+		responses: [][]llm.ToolCallDelta{
+			{
+				{Index: 0, ID: "call_1", Type: "function", Name: "mut_one", Arguments: `{"text":"one"}`},
+				{Index: 1, ID: "call_2", Type: "function", Name: "mut_two", Arguments: `{"text":"two"}`},
+			},
+		},
+		finalContent: "done",
+	}
+
+	a := New(Options{
+		Provider:     provider,
+		Model:        "test",
+		SystemPrompt: "system",
+		ToolRegistry: tools.NewRegistry(tool1, tool2),
+	})
+
+	var out strings.Builder
+	done := make(chan error, 1)
+	go func() {
+		done <- a.RunTurn(context.Background(), "run both", &out, nil)
+	}()
+
+	// Only the first tool should start.
+	select {
+	case name := <-started:
+		if name != "mut_one" {
+			t.Fatalf("expected mut_one to start first, got %q", name)
+		}
+	case <-make(chan struct{}):
+		t.Fatal("timed out waiting for first tool to start")
+	}
+
+	// Second tool should NOT have started yet.
+	select {
+	case name := <-started:
+		t.Fatalf("second tool started too early: %q", name)
+	default:
+		// Expected: second tool hasn't started.
+	}
+
+	close(release)
+	if err := <-done; err != nil {
+		t.Fatal(err)
+	}
+}
+
+// parallelProvider emits a batch of tool calls on the first request, then returns finalContent.
+type parallelProvider struct {
+	responses    [][]llm.ToolCallDelta
+	finalContent string
+	calls        int
+}
+
+func (p *parallelProvider) ChatStream(ctx context.Context, req llm.ChatRequest, emit func(llm.StreamEvent) error) error {
+	p.calls++
+	if p.calls <= len(p.responses) {
+		return emit(llm.StreamEvent{ToolCalls: p.responses[p.calls-1]})
+	}
+	return emit(llm.StreamEvent{Content: p.finalContent})
+}

internal/app/app.go

@@ -0,0 +1,164 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+
+	"agentu/internal/agent"
+	"agentu/internal/session"
+	"agentu/internal/tools"
+	"agentu/internal/tui"
+	"agentu/pkg/config"
+	"agentu/pkg/llm"
+)
+
+type cliOptions struct {
+	configPath string
+	yolo       bool
+	plain      bool
+	themeName  string
+	resumeID   string
+}
+
+func Run() error {
+	opts := parseCLIOptions()
+
+	themeMode, err := tui.ParseThemeMode(opts.themeName)
+	if err != nil {
+		return err
+	}
+
+	cfg, err := loadConfig(opts.configPath)
+	if err != nil {
+		return err
+	}
+
+	providerName, providerConfig, provider := defaultProvider(cfg, http.DefaultClient)
+	assistant := newAssistant(cfg, providerName, providerConfig, provider, opts.yolo, http.DefaultClient)
+	modelManager, err := newSessionManager(cfg, assistant, http.DefaultClient)
+	if err != nil {
+		return err
+	}
+
+	if err := initializeSession(modelManager, opts.resumeID); err != nil {
+		return err
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer stop()
+
+	return runInterface(ctx, assistant, modelManager, providerConfig, cfg.Agent.WorkingDir, opts, themeMode)
+}
+
+func parseCLIOptions() cliOptions {
+	configPath := flag.String("config", config.DefaultPath, "path to YAML config")
+	yolo := flag.Bool("yolo", false, "also enable automatic file writes and shell execution")
+	plain := flag.Bool("plain", false, "use the simple line-based REPL instead of the TUI")
+	themeName := flag.String("theme", "light", "TUI theme: light or dark")
+	resumeID := flag.String("resume", "", "resume a specific session by ID")
+	flag.Parse()
+
+	return cliOptions{
+		configPath: *configPath,
+		yolo:       *yolo,
+		plain:      *plain,
+		themeName:  *themeName,
+		resumeID:   *resumeID,
+	}
+}
+
+func loadConfig(configPath string) (*config.Config, error) {
+	cfg, err := config.Load(configPath)
+	if err == nil {
+		return cfg, nil
+	}
+	if !errors.Is(err, os.ErrNotExist) {
+		return nil, err
+	}
+	if bootstrapErr := bootstrapConfig(configPath); bootstrapErr != nil {
+		return nil, bootstrapErr
+	}
+	return nil, fmt.Errorf("created default config at %s; edit it to set your API key and provider, then restart agentu", configPath)
+}
+
+func defaultProvider(cfg *config.Config, httpClient *http.Client) (string, config.ProviderConfig, llm.Provider) {
+	providerName := cfg.DefaultProviderName()
+	providerConfig := cfg.Providers[providerName]
+	provider := llm.NewOpenAICompatibleClient(providerConfig.BaseURL, providerConfig.APIKey, httpClient)
+	return providerName, providerConfig, provider
+}
+
+func newAssistant(cfg *config.Config, providerName string, providerConfig config.ProviderConfig, provider llm.Provider, yolo bool, httpClient *http.Client) *agent.Agent {
+	return agent.New(agent.Options{
+		Provider:         provider,
+		ProviderName:     providerName,
+		Model:            providerConfig.Model,
+		Thinking:         providerConfig.Thinking,
+		ThinkingParam:    providerConfig.ThinkingParam,
+		ThinkingEnabled:  providerConfig.ThinkingConfigured,
+		SystemPrompt:     systemPrompt(cfg, yolo),
+		ToolRegistry:     newToolRegistry(cfg.Agent.WorkingDir, yolo, httpClient),
+		ToolTimeout:      cfg.Agent.ToolTimeout,
+		MaxContextTokens: maxContextTokens(cfg, providerConfig),
+	})
+}
+
+func systemPrompt(cfg *config.Config, yolo bool) string {
+	instructions := tools.AgentInstructions(cfg.Agent.WorkingDir, yolo)
+	return strings.TrimSpace(cfg.Agent.SystemPrompt + "\n\n" + instructions)
+}
+
+func maxContextTokens(cfg *config.Config, providerConfig config.ProviderConfig) int {
+	if cfg.Agent.MaxContextTokens != 0 {
+		return cfg.Agent.MaxContextTokens
+	}
+	return providerConfig.ContextTokens
+}
+
+func newToolRegistry(workingDir string, yolo bool, httpClient *http.Client) *tools.Registry {
+	var registry *tools.Registry
+	if yolo {
+		registry = tools.Builtins(workingDir)
+	} else {
+		registry = tools.ReadOnlyBuiltins(workingDir)
+	}
+	registry.Register(tools.NewBuiltinSearchTool(httpClient))
+	registry.Register(tools.NewBuiltinFetchTool(httpClient))
+	return registry
+}
+
+func newSessionManager(cfg *config.Config, assistant *agent.Agent, httpClient *http.Client) (*session.Manager, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil, fmt.Errorf("resolve home dir: %w", err)
+	}
+	sessionsDir := filepath.Join(home, ".agentu", "sessions")
+	store, err := session.NewStore(sessionsDir)
+	if err != nil {
+		return nil, fmt.Errorf("init session store: %w", err)
+	}
+	return session.NewManager(cfg, assistant, httpClient, store)
+}
+
+func runInterface(ctx context.Context, assistant *agent.Agent, modelManager *session.Manager, providerConfig config.ProviderConfig, workingDir string, opts cliOptions, themeMode tui.ThemeMode) error {
+	if opts.plain {
+		return repl(ctx, assistant, modelManager)
+	}
+
+	err := tui.Run(ctx, assistant, tui.Options{
+		ModelName:    providerConfig.Model,
+		Yolo:         opts.yolo,
+		ThemeMode:    themeMode,
+		ModelManager: modelManager,
+		WorkingDir:   workingDir,
+	})
+	printExitSession(modelManager)
+	return err
+}

internal/app/bootstrap.go

@@ -0,0 +1,38 @@
+package app
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"agentu/pkg/config"
+)
+
+const defaultConfigContent = `# agentu configuration
+# Replace the placeholder values below with your actual provider settings.
+# See agentu.example.yaml for the full reference.
+providers:
+  default:
+    base_url: https://api.openai.com
+    api_key: YOUR_API_KEY_HERE
+    models:
+      - id: gpt-4o
+        context: 128000
+      - id: gpt-4o-mini
+        context: 128000
+`
+
+func bootstrapConfig(configPath string) error {
+	resolved, err := config.ResolvePath(configPath)
+	if err != nil {
+		return fmt.Errorf("resolve config path: %w", err)
+	}
+	dir := filepath.Dir(resolved)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("create config directory: %w", err)
+	}
+	if err := os.WriteFile(resolved, []byte(defaultConfigContent), 0o644); err != nil {
+		return fmt.Errorf("write default config: %w", err)
+	}
+	return nil
+}

internal/app/main_test.go

@@ -0,0 +1,101 @@
+package app
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+
+	"agentu/internal/agent"
+	"agentu/internal/session"
+	"agentu/pkg/config"
+	"agentu/pkg/llm"
+)
+
+type startupProvider struct{}
+
+func (p *startupProvider) ChatStream(ctx context.Context, req llm.ChatRequest, emit func(llm.StreamEvent) error) error {
+	return emit(llm.StreamEvent{Content: "ok"})
+}
+
+func startupTestManager(t *testing.T) (*session.Manager, *agent.Agent) {
+	t.Helper()
+	cfg := &config.Config{
+		Providers: map[string]config.ProviderConfig{
+			"one": {
+				Name:          "one",
+				BaseURL:       "https://one.example.com",
+				APIKey:        "sk-test",
+				Model:         "model-a",
+				Models:        []string{"model-a"},
+				Thinking:      "none",
+				ThinkingParam: "thinking",
+			},
+		},
+	}
+	assistant := agent.New(agent.Options{
+		Provider:     &startupProvider{},
+		ProviderName: "one",
+		Model:        "model-a",
+	})
+	store, err := session.NewStore(filepath.Join(t.TempDir(), "sessions"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	manager, err := session.NewManager(cfg, assistant, nil, store)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return manager, assistant
+}
+
+func TestInitializeSessionStartsNewByDefault(t *testing.T) {
+	manager, assistant := startupTestManager(t)
+	if _, err := manager.NewSession(); err != nil {
+		t.Fatalf("new session: %v", err)
+	}
+	savedID := manager.CurrentSessionID()
+	assistant.SetMessages([]llm.Message{{Role: llm.RoleUser, Content: "old context"}})
+	if err := manager.Save(); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+
+	if err := initializeSession(manager, ""); err != nil {
+		t.Fatalf("initialize: %v", err)
+	}
+	if manager.CurrentSessionID() == savedID {
+		t.Fatalf("default startup resumed latest session %s", savedID)
+	}
+	for _, msg := range assistant.Messages() {
+		if msg.Content == "old context" {
+			t.Fatal("default startup carried old context into new session")
+		}
+	}
+}
+
+func TestInitializeSessionResumesExplicitID(t *testing.T) {
+	manager, assistant := startupTestManager(t)
+	if _, err := manager.NewSession(); err != nil {
+		t.Fatalf("new session: %v", err)
+	}
+	savedID := manager.CurrentSessionID()
+	assistant.SetMessages([]llm.Message{{Role: llm.RoleUser, Content: "old context"}})
+	if err := manager.Save(); err != nil {
+		t.Fatalf("save: %v", err)
+	}
+
+	if err := initializeSession(manager, savedID); err != nil {
+		t.Fatalf("initialize: %v", err)
+	}
+	if manager.CurrentSessionID() != savedID {
+		t.Fatalf("expected resumed session %s, got %s", savedID, manager.CurrentSessionID())
+	}
+	found := false
+	for _, msg := range assistant.Messages() {
+		if msg.Content == "old context" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatal("explicit resume did not restore saved context")
+	}
+}

internal/app/repl.go

@@ -0,0 +1,60 @@
+package app
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"agentu/internal/agent"
+	"agentu/internal/session"
+)
+
+func repl(ctx context.Context, assistant *agent.Agent, modelManager *session.Manager) error {
+	scanner := bufio.NewScanner(os.Stdin)
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+
+	fmt.Println("agentu")
+	fmt.Println("Type /exit to quit, /clear to reset context, /compact to compress context.")
+	for {
+		fmt.Print("> ")
+		if !scanner.Scan() {
+			if err := scanner.Err(); err != nil {
+				return err
+			}
+			fmt.Println()
+			printExitSession(modelManager)
+			return nil
+		}
+
+		input := strings.TrimSpace(scanner.Text())
+		switch input {
+		case "":
+			continue
+		case "/exit", "/quit":
+			printExitSession(modelManager)
+			return nil
+		case "/clear":
+			assistant.Clear()
+			fmt.Println("context cleared")
+			continue
+		case "/compact":
+			if err := assistant.Compact(ctx); err != nil {
+				fmt.Fprintln(os.Stderr, "compact error:", err)
+			} else {
+				fmt.Println("context compacted")
+				if modelManager != nil {
+					_ = modelManager.Save()
+				}
+			}
+			continue
+		}
+
+		if err := assistant.RunTurn(ctx, input, os.Stdout, os.Stderr); err != nil {
+			fmt.Fprintln(os.Stderr, "\nerror:", err)
+		}
+		_ = modelManager.Save()
+		fmt.Println()
+	}
+}

internal/app/session_startup.go

@@ -0,0 +1,38 @@
+package app
+
+import (
+	"fmt"
+	"os"
+
+	"agentu/internal/session"
+)
+
+func initializeSession(modelManager *session.Manager, resumeID string) error {
+	if resumeID != "" {
+		if err := modelManager.Resume(resumeID); err != nil {
+			return fmt.Errorf("resume session: %w", err)
+		}
+		return nil
+	}
+	if _, err := modelManager.NewSession(); err != nil {
+		return fmt.Errorf("start new session: %w", err)
+	}
+	return nil
+}
+
+func printExitSession(m *session.Manager) {
+	if m == nil {
+		return
+	}
+	_ = m.Save()
+	id := m.CurrentSessionID()
+	name := m.CurrentSessionName()
+	if id != "" {
+		if name != "" && name != id {
+			fmt.Fprintf(os.Stderr, "session: %s (%s)\n", id, name)
+		} else {
+			fmt.Fprintf(os.Stderr, "session: %s\n", id)
+		}
+		fmt.Fprintf(os.Stderr, "resume:  agentu --resume %s\n", id)
+	}
+}

internal/session/manager.go

@@ -8,8 +8,8 @@ import (
 	"time"
 
 	"agentu/internal/agent"
-	"agentu/internal/config"
-	"agentu/internal/llm"
+	"agentu/pkg/config"
+	"agentu/pkg/llm"
 )
 
 type Manager struct {

internal/session/manager_test.go

@@ -7,8 +7,8 @@ import (
 	"testing"
 
 	"agentu/internal/agent"
-	"agentu/internal/config"
-	"agentu/internal/llm"
+	"agentu/pkg/config"
+	"agentu/pkg/llm"
 )
 
 type recordingProvider struct {

internal/session/store.go

@@ -11,7 +11,7 @@ import (
 	"strings"
 	"time"
 
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 )
 
 // Session represents a persisted conversation.

internal/session/store_test.go

@@ -5,7 +5,7 @@ import (
 	"path/filepath"
 	"testing"
 
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 )
 
 func tempStore(t *testing.T) *Store {

internal/tools/code.go

@@ -16,7 +16,7 @@ import (
 	"sort"
 	"strings"
 
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 )
 
 const defaultCodeSymbolFileLimit = 50

internal/tools/file.go

@@ -13,7 +13,7 @@ import (
 	"sort"
 	"strings"
 
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 )
 
 type FileReadTool struct {
@@ -81,6 +81,7 @@ type FileWriteTool struct {
 func NewFileWriteTool(workingDir string) *FileWriteTool {
 	return &FileWriteTool{workingDir: workingDir}
 }
+func (*FileWriteTool) Mutates() bool { return true }
 
 func (t *FileWriteTool) Definition() llm.Tool {
 	return llm.Tool{

internal/tools/file_edit.go

@@ -0,0 +1,178 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+
+	"agentu/pkg/llm"
+)
+
+type FileEditTool struct {
+	workingDir string
+}
+
+func NewFileEditTool(workingDir string) *FileEditTool {
+	return &FileEditTool{workingDir: workingDir}
+}
+
+func (*FileEditTool) Mutates() bool { return true }
+
+func (t *FileEditTool) Definition() llm.Tool {
+	return llm.Tool{
+		Type: "function",
+		Function: llm.ToolFunction{
+			Name:        "file_edit",
+			Description: "Edit an existing UTF-8 text file by replacing an inclusive 1-based line range or an exact old text pattern.",
+			Parameters: JSONSchema(`{
+  "type": "object",
+  "properties": {
+    "path": {"type": "string", "description": "Existing file path relative to the configured agent working directory."},
+    "start_line": {"type": "integer", "description": "1-based first line for a line-range edit."},
+    "end_line": {"type": "integer", "description": "Optional 1-based final line; defaults to start_line when omitted."},
+    "old": {"type": "string", "description": "Exact text to replace for a pattern edit; not regex."},
+    "new": {"type": "string", "description": "Replacement text; may be empty string for deletion."},
+    "replace_all": {"type": "boolean", "description": "When true, replace every exact old occurrence; otherwise require exactly one occurrence."}
+  },
+  "required": ["path", "new"],
+  "additionalProperties": false
+}`),
+		},
+	}
+}
+
+type fileEditArgs struct {
+	Path       string  `json:"path"`
+	StartLine  int     `json:"start_line"`
+	EndLine    int     `json:"end_line"`
+	Old        string  `json:"old"`
+	New        *string `json:"new"`
+	ReplaceAll bool    `json:"replace_all"`
+}
+
+func (t *FileEditTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
+	var args fileEditArgs
+	if err := json.Unmarshal(raw, &args); err != nil {
+		return "", fmt.Errorf("parse arguments: %w", err)
+	}
+	if strings.TrimSpace(args.Path) == "" {
+		return "", errors.New("path is required")
+	}
+	if args.New == nil {
+		return "", errors.New("new is required")
+	}
+	path, err := resolvePath(t.workingDir, args.Path)
+	if err != nil {
+		return "", err
+	}
+
+	info, err := os.Stat(path)
+	if err != nil {
+		return "", fmt.Errorf("cannot access %s: %w", args.Path, err)
+	}
+	if info.IsDir() {
+		return "", fmt.Errorf("%s is a directory, not a file", args.Path)
+	}
+	perm := info.Mode().Perm()
+
+	hasLine := args.StartLine > 0 || args.EndLine > 0
+	hasOld := strings.TrimSpace(args.Old) != ""
+
+	if hasLine && hasOld {
+		return "", errors.New("provide either start_line/end_line or old, not both")
+	}
+	if !hasLine && !hasOld {
+		return "", errors.New("provide either start_line/end_line or old")
+	}
+
+	if err := ctx.Err(); err != nil {
+		return "", err
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return "", err
+	}
+	content := string(data)
+
+	var result string
+	if hasOld {
+		result, err = editByPattern(content, args.Path, args.Old, *args.New, args.ReplaceAll)
+	} else {
+		result, err = editByLineRange(content, args.Path, args.StartLine, args.EndLine, *args.New)
+	}
+	if err != nil {
+		return "", err
+	}
+
+	if err := ctx.Err(); err != nil {
+		return "", err
+	}
+	if err := os.WriteFile(path, []byte(result), perm); err != nil {
+		return "", err
+	}
+
+	switch {
+	case hasOld:
+		count := strings.Count(content, args.Old)
+		if args.ReplaceAll {
+			return fmt.Sprintf("edited %s: replaced %d occurrences", args.Path, count), nil
+		}
+		return fmt.Sprintf("edited %s: replaced 1 occurrence", args.Path), nil
+	default:
+		endLine := args.EndLine
+		if endLine == 0 {
+			endLine = args.StartLine
+		}
+		return fmt.Sprintf("edited %s: replaced lines %d-%d", args.Path, args.StartLine, endLine), nil
+	}
+}
+
+func editByLineRange(content, displayPath string, startLine, endLine int, replacement string) (string, error) {
+	if startLine < 1 {
+		return "", errors.New("start_line must be >= 1")
+	}
+	if endLine == 0 {
+		endLine = startLine
+	}
+	if endLine < startLine {
+		return "", fmt.Errorf("end_line (%d) must be >= start_line (%d)", endLine, startLine)
+	}
+
+	lines := strings.Split(content, "\n")
+	if startLine > len(lines) {
+		return "", fmt.Errorf("line range %d-%d is outside file with %d lines", startLine, endLine, len(lines))
+	}
+	if endLine > len(lines) {
+		return "", fmt.Errorf("line range %d-%d is outside file with %d lines", startLine, endLine, len(lines))
+	}
+
+	var b strings.Builder
+	b.WriteString(strings.Join(lines[:startLine-1], "\n"))
+	if startLine > 1 {
+		b.WriteString("\n")
+	}
+	b.WriteString(replacement)
+	if endLine < len(lines) {
+		if !strings.HasSuffix(replacement, "\n") && replacement != "" {
+			b.WriteString("\n")
+		}
+		b.WriteString(strings.Join(lines[endLine:], "\n"))
+	}
+
+	return b.String(), nil
+}
+
+func editByPattern(content, displayPath, old, replacement string, replaceAll bool) (string, error) {
+	count := strings.Count(content, old)
+	if count == 0 {
+		return "", errors.New("old text not found")
+	}
+	if !replaceAll && count != 1 {
+		return "", fmt.Errorf("old text matched %d occurrences; set replace_all=true or provide a more specific old value", count)
+	}
+	return strings.ReplaceAll(content, old, replacement), nil
+}

internal/tools/file_edit_test.go

@@ -0,0 +1,136 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestFileEditReplacesLineRange(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "notes.txt")
+	if err := os.WriteFile(path, []byte("one\ntwo\nthree\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	edit := NewFileEditTool(dir)
+	out, err := edit.Execute(context.Background(), json.RawMessage(`{"path":"notes.txt","start_line":2,"end_line":2,"new":"TWO\n"}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "replaced lines 2-2") {
+		t.Fatalf("output = %q", out)
+	}
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "one\nTWO\nthree\n" {
+		t.Fatalf("file content = %q", string(got))
+	}
+}
+
+func TestFileEditReplacesExactPattern(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "notes.txt")
+	if err := os.WriteFile(path, []byte("alpha beta alpha"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	edit := NewFileEditTool(dir)
+	out, err := edit.Execute(context.Background(), json.RawMessage(`{"path":"notes.txt","old":"beta","new":"BETA"}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "replaced 1 occurrence") {
+		t.Fatalf("output = %q", out)
+	}
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "alpha BETA alpha" {
+		t.Fatalf("file content = %q", string(got))
+	}
+}
+
+func TestFileEditRejectsAmbiguousPattern(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "notes.txt")
+	if err := os.WriteFile(path, []byte("x x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	edit := NewFileEditTool(dir)
+	_, err := edit.Execute(context.Background(), json.RawMessage(`{"path":"notes.txt","old":"x","new":"y"}`))
+	if err == nil {
+		t.Fatal("expected error for ambiguous pattern")
+	}
+	if !strings.Contains(err.Error(), "matched 2 occurrences") {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+func TestFileEditReplaceAll(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "notes.txt")
+	if err := os.WriteFile(path, []byte("x x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	edit := NewFileEditTool(dir)
+	out, err := edit.Execute(context.Background(), json.RawMessage(`{"path":"notes.txt","old":"x","new":"y","replace_all":true}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "replaced 2 occurrences") {
+		t.Fatalf("output = %q", out)
+	}
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "y y" {
+		t.Fatalf("file content = %q", string(got))
+	}
+}
+
+func TestFileEditRejectsEscapingPath(t *testing.T) {
+	dir := t.TempDir()
+	edit := NewFileEditTool(dir)
+	_, err := edit.Execute(context.Background(), json.RawMessage(`{"path":"../outside.txt","old":"x","new":"y"}`))
+	if err == nil {
+		t.Fatal("expected error for escaping path")
+	}
+	if !strings.Contains(err.Error(), "escapes") {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+func TestFileEditRejectsMissingNew(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "notes.txt")
+	if err := os.WriteFile(path, []byte("hello"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	edit := NewFileEditTool(dir)
+	_, err := edit.Execute(context.Background(), json.RawMessage(`{"path":"notes.txt","old":"hello"}`))
+	if err == nil {
+		t.Fatal("expected error for missing new")
+	}
+	if !strings.Contains(err.Error(), "new is required") {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+func TestFileEditRejectsNonExistentFile(t *testing.T) {
+	dir := t.TempDir()
+	edit := NewFileEditTool(dir)
+	_, err := edit.Execute(context.Background(), json.RawMessage(`{"path":"missing.txt","old":"x","new":"y"}`))
+	if err == nil {
+		t.Fatal("expected error for non-existent file")
+	}
+}

internal/tools/git.go

@@ -0,0 +1,246 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"agentu/pkg/llm"
+)
+
+const (
+	defaultGitLogMaxCount = 20
+	maxGitLogMaxCount     = 100
+)
+
+func runGit(ctx context.Context, workingDir string, args ...string) (string, error) {
+	gitArgs := append([]string{"-C", workingDir}, args...)
+	cmd := exec.CommandContext(ctx, "git", gitArgs...)
+	output, err := cmd.CombinedOutput()
+	text := FormatResult(string(output))
+	if err != nil {
+		if strings.Contains(err.Error(), "context deadline exceeded") || strings.Contains(err.Error(), "signal: killed") {
+			if text != "" {
+				return text, fmt.Errorf("git command timed out: %w", err)
+			}
+			return "", fmt.Errorf("git command timed out: %w", err)
+		}
+		if text != "" {
+			return text, fmt.Errorf("git command failed: %w", err)
+		}
+		return "", fmt.Errorf("git command failed: %w", err)
+	}
+	return text, nil
+}
+
+func gitPathspec(baseDir, path string) (string, error) {
+	if strings.TrimSpace(path) == "" {
+		return "", nil
+	}
+	resolved, err := resolvePath(baseDir, path)
+	if err != nil {
+		return "", err
+	}
+	rel, err := filepath.Rel(baseDir, resolved)
+	if err != nil {
+		return "", err
+	}
+	return filepath.ToSlash(filepath.Clean(rel)), nil
+}
+
+func normalizeGitLogMaxCount(value int) int {
+	if value <= 0 {
+		return defaultGitLogMaxCount
+	}
+	if value > maxGitLogMaxCount {
+		return maxGitLogMaxCount
+	}
+	return value
+}
+
+// git_status
+
+type GitStatusTool struct {
+	workingDir string
+}
+
+func NewGitStatusTool(workingDir string) *GitStatusTool {
+	return &GitStatusTool{workingDir: workingDir}
+}
+
+func (t *GitStatusTool) Definition() llm.Tool {
+	return llm.Tool{
+		Type: "function",
+		Function: llm.ToolFunction{
+			Name:        "git_status",
+			Description: "Show changed files using git status --short.",
+			Parameters: JSONSchema(`{
+  "type": "object",
+  "properties": {
+    "path": {"type": "string", "description": "Optional path to limit status to. Relative paths are resolved from the configured agent working directory."}
+  },
+  "additionalProperties": false
+}`),
+		},
+	}
+}
+
+type gitStatusArgs struct {
+	Path string `json:"path"`
+}
+
+func (t *GitStatusTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
+	var args gitStatusArgs
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &args); err != nil {
+			return "", fmt.Errorf("parse arguments: %w", err)
+		}
+	}
+	gitArgs := []string{"status", "--short"}
+	if args.Path != "" {
+		pathspec, err := gitPathspec(t.workingDir, args.Path)
+		if err != nil {
+			return "", err
+		}
+		gitArgs = append(gitArgs, "--", pathspec)
+	}
+	text, err := runGit(ctx, t.workingDir, gitArgs...)
+	if err != nil {
+		return text, err
+	}
+	if strings.TrimSpace(text) == "" {
+		return "Working tree clean.", nil
+	}
+	return "Changed files:\n" + text, nil
+}
+
+// git_diff
+
+type GitDiffTool struct {
+	workingDir string
+}
+
+func NewGitDiffTool(workingDir string) *GitDiffTool {
+	return &GitDiffTool{workingDir: workingDir}
+}
+
+func (t *GitDiffTool) Definition() llm.Tool {
+	return llm.Tool{
+		Type: "function",
+		Function: llm.ToolFunction{
+			Name:        "git_diff",
+			Description: "Show unstaged or staged git diff output, optionally as --stat.",
+			Parameters: JSONSchema(`{
+  "type": "object",
+  "properties": {
+    "path": {"type": "string", "description": "Optional path to limit diff to. Relative paths are resolved from the configured agent working directory."},
+    "staged": {"type": "boolean", "description": "Show staged diff instead of unstaged."},
+    "stat": {"type": "boolean", "description": "Show diffstat summary instead of full diff."}
+  },
+  "additionalProperties": false
+}`),
+		},
+	}
+}
+
+type gitDiffArgs struct {
+	Path   string `json:"path"`
+	Staged bool   `json:"staged"`
+	Stat   bool   `json:"stat"`
+}
+
+func (t *GitDiffTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
+	var args gitDiffArgs
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &args); err != nil {
+			return "", fmt.Errorf("parse arguments: %w", err)
+		}
+	}
+	gitArgs := []string{"diff"}
+	if args.Staged {
+		gitArgs = append(gitArgs, "--cached")
+	}
+	if args.Stat {
+		gitArgs = append(gitArgs, "--stat")
+	}
+	if args.Path != "" {
+		pathspec, err := gitPathspec(t.workingDir, args.Path)
+		if err != nil {
+			return "", err
+		}
+		gitArgs = append(gitArgs, "--", pathspec)
+	}
+	text, err := runGit(ctx, t.workingDir, gitArgs...)
+	if err != nil {
+		return text, err
+	}
+	if strings.TrimSpace(text) == "" {
+		if args.Staged {
+			return "No staged diff.", nil
+		}
+		return "No unstaged diff.", nil
+	}
+	return text, nil
+}
+
+// git_log
+
+type GitLogTool struct {
+	workingDir string
+}
+
+func NewGitLogTool(workingDir string) *GitLogTool {
+	return &GitLogTool{workingDir: workingDir}
+}
+
+func (t *GitLogTool) Definition() llm.Tool {
+	return llm.Tool{
+		Type: "function",
+		Function: llm.ToolFunction{
+			Name:        "git_log",
+			Description: "Show recent git commits with git log --oneline --decorate.",
+			Parameters: JSONSchema(`{
+  "type": "object",
+  "properties": {
+    "path": {"type": "string", "description": "Optional path to limit log to. Relative paths are resolved from the configured agent working directory."},
+    "max_count": {"type": "integer", "description": "Maximum number of commits to show. Defaults to 20, capped at 100."}
+  },
+  "additionalProperties": false
+}`),
+		},
+	}
+}
+
+type gitLogArgs struct {
+	Path     string `json:"path"`
+	MaxCount int    `json:"max_count"`
+}
+
+func (t *GitLogTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
+	var args gitLogArgs
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &args); err != nil {
+			return "", fmt.Errorf("parse arguments: %w", err)
+		}
+	}
+	maxCount := normalizeGitLogMaxCount(args.MaxCount)
+	gitArgs := []string{"log", "--oneline", "--decorate", fmt.Sprintf("-n%d", maxCount)}
+	if args.Path != "" {
+		pathspec, err := gitPathspec(t.workingDir, args.Path)
+		if err != nil {
+			return "", err
+		}
+		gitArgs = append(gitArgs, "--", pathspec)
+	}
+	text, err := runGit(ctx, t.workingDir, gitArgs...)
+	if err != nil {
+		return text, err
+	}
+	if strings.TrimSpace(text) == "" {
+		return "No git history.", nil
+	}
+	return text, nil
+}

internal/tools/git_test.go

@@ -0,0 +1,142 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func requireGit(t *testing.T) {
+	t.Helper()
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not installed")
+	}
+}
+
+func runGitForTest(t *testing.T, dir string, args ...string) {
+	t.Helper()
+	gitArgs := append([]string{"-C", dir}, args...)
+	cmd := exec.Command("git", gitArgs...)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %v failed: %v\n%s", args, err, out)
+	}
+}
+
+func initTestRepo(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	runGitForTest(t, dir, "init")
+	runGitForTest(t, dir, "-c", "user.email=test@example.com", "-c", "user.name=Test", "commit", "--allow-empty", "-m", "initial")
+	return dir
+}
+
+func TestGitStatusToolShowsChangedFiles(t *testing.T) {
+	requireGit(t)
+	dir := initTestRepo(t)
+
+	path := filepath.Join(dir, "tracked.txt")
+	if err := os.WriteFile(path, []byte("hello"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	runGitForTest(t, dir, "add", "tracked.txt")
+	runGitForTest(t, dir, "-c", "user.email=test@example.com", "-c", "user.name=Test", "commit", "-m", "add tracked")
+
+	if err := os.WriteFile(path, []byte("world"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	tool := NewGitStatusTool(dir)
+	out, err := tool.Execute(context.Background(), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "Changed files:") {
+		t.Fatalf("output missing 'Changed files:': %q", out)
+	}
+	if !strings.Contains(out, "M tracked.txt") {
+		t.Fatalf("output missing 'M tracked.txt': %q", out)
+	}
+}
+
+func TestGitDiffToolShowsUnstagedDiff(t *testing.T) {
+	requireGit(t)
+	dir := initTestRepo(t)
+
+	path := filepath.Join(dir, "tracked.txt")
+	if err := os.WriteFile(path, []byte("hello"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	runGitForTest(t, dir, "add", "tracked.txt")
+	runGitForTest(t, dir, "-c", "user.email=test@example.com", "-c", "user.name=Test", "commit", "-m", "add tracked")
+
+	if err := os.WriteFile(path, []byte("world"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	tool := NewGitDiffTool(dir)
+	out, err := tool.Execute(context.Background(), nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "diff --git") {
+		t.Fatalf("output missing 'diff --git': %q", out)
+	}
+}
+
+func TestGitDiffToolShowsStat(t *testing.T) {
+	requireGit(t)
+	dir := initTestRepo(t)
+
+	path := filepath.Join(dir, "tracked.txt")
+	if err := os.WriteFile(path, []byte("hello"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	runGitForTest(t, dir, "add", "tracked.txt")
+	runGitForTest(t, dir, "-c", "user.email=test@example.com", "-c", "user.name=Test", "commit", "-m", "add tracked")
+
+	if err := os.WriteFile(path, []byte("world"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	tool := NewGitDiffTool(dir)
+	out, err := tool.Execute(context.Background(), json.RawMessage(`{"stat":true}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "tracked.txt") {
+		t.Fatalf("output missing 'tracked.txt': %q", out)
+	}
+}
+
+func TestGitLogToolShowsCommits(t *testing.T) {
+	requireGit(t)
+	dir := initTestRepo(t)
+
+	tool := NewGitLogTool(dir)
+	out, err := tool.Execute(context.Background(), json.RawMessage(`{"max_count":1}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "initial") {
+		t.Fatalf("output missing 'initial': %q", out)
+	}
+}
+
+func TestGitToolsRejectEscapingPath(t *testing.T) {
+	requireGit(t)
+	dir := initTestRepo(t)
+
+	tool := NewGitStatusTool(dir)
+	_, err := tool.Execute(context.Background(), json.RawMessage(`{"path":"../outside"}`))
+	if err == nil {
+		t.Fatal("expected error for escaping path")
+	}
+	if !strings.Contains(err.Error(), "escapes") {
+		t.Fatalf("error = %v", err)
+	}
+}

internal/tools/shell.go

@@ -9,7 +9,7 @@ import (
 	"os/exec"
 	"strings"
 
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 )
 
 type ShellRunTool struct {
@@ -19,6 +19,7 @@ type ShellRunTool struct {
 func NewShellRunTool(workingDir string) *ShellRunTool {
 	return &ShellRunTool{workingDir: workingDir}
 }
+func (*ShellRunTool) Mutates() bool { return true }
 
 func (t *ShellRunTool) Definition() llm.Tool {
 	return llm.Tool{

internal/tools/tools.go

@@ -7,7 +7,7 @@ import (
 	"sort"
 	"strings"
 
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 )
 
 const MaxToolOutputBytes = 64 * 1024
@@ -19,6 +19,18 @@ type Tool interface {
 	Execute(ctx context.Context, args json.RawMessage) (string, error)
 }
 
+// MutatingTool is optionally implemented by tools that modify external state.
+// It is used by the agent to determine whether tool calls can run in parallel.
+type MutatingTool interface {
+	Mutates() bool
+}
+
+// IsMutating reports whether tool implements MutatingTool and returns true.
+func IsMutating(tool Tool) bool {
+	mutating, ok := tool.(MutatingTool)
+	return ok && mutating.Mutates()
+}
+
 type Registry struct {
 	tools   map[string]Tool
 	primary []string
@@ -66,30 +78,39 @@ func ReadOnlyBuiltins(workingDir string) *Registry {
 	fileList := NewFileListTool(workingDir)
 	fileSearch := NewFileSearchTool(workingDir)
 	codeSymbols := NewCodeSymbolsTool(workingDir)
+	gitStatus := NewGitStatusTool(workingDir)
+	gitDiff := NewGitDiffTool(workingDir)
+	gitLog := NewGitLogTool(workingDir)
 
-	registry := NewRegistry(fileRead, fileList, fileSearch, codeSymbols)
+	registry := NewRegistry(fileRead, fileList, fileSearch, codeSymbols, gitStatus, gitDiff, gitLog)
 	registry.RegisterAlias("file.read", fileRead)
 	registry.RegisterAlias("file.list", fileList)
 	registry.RegisterAlias("file.search", fileSearch)
 	registry.RegisterAlias("code.symbols", codeSymbols)
+	registry.RegisterAlias("git.status", gitStatus)
+	registry.RegisterAlias("git.diff", gitDiff)
+	registry.RegisterAlias("git.log", gitLog)
 	return registry
 }
 
 func Builtins(workingDir string) *Registry {
 	registry := ReadOnlyBuiltins(workingDir)
 	fileWrite := NewFileWriteTool(workingDir)
+	fileEdit := NewFileEditTool(workingDir)
 	shellRun := NewShellRunTool(workingDir)
 	registry.Register(fileWrite)
+	registry.Register(fileEdit)
 	registry.Register(shellRun)
 	registry.RegisterAlias("file.write", fileWrite)
+	registry.RegisterAlias("file.edit", fileEdit)
 	registry.RegisterAlias("shell.run", shellRun)
 	return registry
 }
 
 func AgentInstructions(workingDir string, yolo bool) string {
 	searchInstructions := webSearchInstructions()
-	readOnlyTools := "file_list, file_read, file_search, code_symbols, web_search, web_fetch"
-	yoloTools := "file_list, file_read, file_search, code_symbols, file_write, shell_run, web_search, web_fetch"
+	readOnlyTools := "file_list, file_read, file_search, code_symbols, git_status, git_diff, git_log, web_search, web_fetch"
+	yoloTools := "file_list, file_read, file_search, code_symbols, file_write, file_edit, shell_run, git_status, git_diff, git_log, web_search, web_fetch"
 	if yolo {
 		return fmt.Sprintf(`Local project context:
 - The project working directory is %q.
@@ -99,7 +120,9 @@ func AgentInstructions(workingDir string, yolo bool) string {
 - When the user asks to inspect, list, search, or read project files, use file_list, file_search, and file_read instead of saying you cannot access local files.
 - When the user asks about code structure, symbols, functions, methods, types, or definitions in Go files, use code_symbols before reading whole files.
 - When the user asks to run, execute, test, check, debug, or inspect a shell command, use shell_run. This includes local commands written in backticks, such as go, make, git, pwd, ls, ps, and similar terminal commands.
+- When editing existing files, prefer file_edit for small or localized changes; use file_write only for creating files, replacing whole files intentionally, or appending.
 - Do not use file tools as a substitute for a command execution request.
+- When the user asks about changed files, diffs, or git history, use git_status, git_diff, or git_log instead of shell_run.
 - Do not start interactive or long-running sessions. Prefer bounded, non-interactive local commands with clear completion conditions.
 - %s
 - Tool paths should normally be relative to the project working directory.
@@ -113,6 +136,7 @@ func AgentInstructions(workingDir string, yolo bool) string {
 - When the user asks to inspect, list, search, or read project files, use file_list, file_search, and file_read instead of saying you cannot access local files.
 - When the user asks about code structure, symbols, functions, methods, types, or definitions in Go files, use code_symbols before reading whole files.
 - Shell command execution is disabled in this mode. When the user asks to run, execute, test, check, debug, or inspect a shell command, do not use file tools as a substitute; explain that they need to restart agentu with --yolo to enable shell_run.
+- When the user asks about changed files, diffs, or git history, use git_status, git_diff, or git_log instead of shell_run.
 - %s
 - Tool paths should normally be relative to the project working directory.
 - Available tools: %s.`, workingDir, searchInstructions, readOnlyTools)

internal/tools/tools_test.go

@@ -104,12 +104,12 @@ func TestReadOnlyBuiltinsExposeOpenAICompatibleNamesAndAliases(t *testing.T) {
 		}
 	}
 
-	for _, want := range []string{"file_list", "file_read", "file_search", "code_symbols"} {
+	for _, want := range []string{"file_list", "file_read", "file_search", "code_symbols", "git_status", "git_diff", "git_log"} {
 		if !slices.Contains(names, want) {
 			t.Fatalf("definitions missing %s: %#v", want, names)
 		}
 	}
-	for _, alias := range []string{"file.list", "file.read", "file.search", "code.symbols"} {
+	for _, alias := range []string{"file.list", "file.read", "file.search", "code.symbols", "git.status", "git.diff", "git.log"} {
 		if _, ok := registry.Get(alias); !ok {
 			t.Fatalf("alias missing: %s", alias)
 		}
@@ -117,6 +117,9 @@ func TestReadOnlyBuiltinsExposeOpenAICompatibleNamesAndAliases(t *testing.T) {
 	if _, ok := registry.Get("file_write"); ok {
 		t.Fatal("read-only registry should not expose file_write")
 	}
+	if _, ok := registry.Get("file_edit"); ok {
+		t.Fatal("read-only registry should not expose file_edit")
+	}
 }
 
 func TestCodeSymbolsToolListsGoSymbols(t *testing.T) {
@@ -170,7 +173,7 @@ func TestRegistryCanExposeWebSearch(t *testing.T) {
 
 func TestBuiltinsExposeYoloTools(t *testing.T) {
 	registry := Builtins(t.TempDir())
-	for _, name := range []string{"file_write", "shell_run", "file.write", "shell.run"} {
+	for _, name := range []string{"file_write", "file_edit", "shell_run", "file.write", "file.edit", "shell.run"} {
 		if _, ok := registry.Get(name); !ok {
 			t.Fatalf("tool missing: %s", name)
 		}
@@ -179,14 +182,14 @@ func TestBuiltinsExposeYoloTools(t *testing.T) {
 
 func TestAgentInstructionsExplainCommandModes(t *testing.T) {
 	readOnly := AgentInstructions("/tmp/project", false)
-	for _, want := range []string{"Shell command execution is disabled", "--yolo", "Do not call tools for greetings", "Do not explore the project preemptively", "Do not call file_list just to discover context"} {
+	for _, want := range []string{"Shell command execution is disabled", "--yolo", "Do not call tools for greetings", "Do not explore the project preemptively", "Do not call file_list just to discover context", "git_status, git_diff, git_log"} {
 		if !strings.Contains(readOnly, want) {
 			t.Fatalf("read-only instructions missing %q:\n%s", want, readOnly)
 		}
 	}
 
 	yolo := AgentInstructions("/tmp/project", true)
-	for _, want := range []string{"use shell_run", "commands written in backticks", "Do not start interactive", "non-interactive local commands", "Do not call tools for greetings"} {
+	for _, want := range []string{"use shell_run", "commands written in backticks", "Do not start interactive", "non-interactive local commands", "Do not call tools for greetings", "prefer file_edit"} {
 		if !strings.Contains(yolo, want) {
 			t.Fatalf("yolo instructions missing %q:\n%s", want, yolo)
 		}
@@ -195,7 +198,7 @@ func TestAgentInstructionsExplainCommandModes(t *testing.T) {
 
 func TestAgentInstructionsExplainWebSearch(t *testing.T) {
 	withSearch := AgentInstructions("/tmp/project", false)
-	for _, want := range []string{"use web_search", "Use web_fetch", "latest information", "source URLs", "Available tools: file_list, file_read, file_search, code_symbols, web_search, web_fetch"} {
+	for _, want := range []string{"use web_search", "Use web_fetch", "latest information", "source URLs", "Available tools: file_list, file_read, file_search, code_symbols, git_status, git_diff, git_log, web_search, web_fetch"} {
 		if !strings.Contains(withSearch, want) {
 			t.Fatalf("web search instructions missing %q:\n%s", want, withSearch)
 		}
@@ -257,3 +260,16 @@ func TestResolvePathRejectsDotDotThatEscapes(t *testing.T) {
 		t.Fatal("expected error for path escaping via ..")
 	}
 }
+
+func TestIsMutating(t *testing.T) {
+	dir := t.TempDir()
+	if IsMutating(NewFileReadTool(dir)) {
+		t.Fatal("FileReadTool should not be mutating")
+	}
+	if !IsMutating(NewFileWriteTool(dir)) {
+		t.Fatal("FileWriteTool should be mutating")
+	}
+	if !IsMutating(NewShellRunTool(dir)) {
+		t.Fatal("ShellRunTool should be mutating")
+	}
+}

internal/tools/web_builtin.go

@@ -10,7 +10,7 @@ import (
 	"net/url"
 	"strings"
 
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 
 	"golang.org/x/net/html"
 )

internal/tui/app.go

@@ -6,10 +6,12 @@ import (
 	"fmt"
 	"io"
 	"math"
+	"sort"
 	"strings"
+	"unicode"
 
 	"agentu/internal/agent"
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 
 	"github.com/charmbracelet/bubbles/spinner"
 	"github.com/charmbracelet/bubbles/textarea"
@@ -21,6 +23,8 @@ import (
 const (
 	minInputLines          = 1
 	maxInputLines          = 6
+	maxCommandPaletteItems = 8
+	maxInputHistory        = 100
 )
 
 type Options struct {
@@ -89,6 +93,10 @@ type model struct {
 	messages     []message
 	status       string
 	contextUsage string
+	inputHistory []string
+	historyIndex int
+	draftInput   string
+
 	running bool
 	cancel  context.CancelFunc
 	events  <-chan tea.Msg
@@ -120,6 +128,11 @@ type slashCommand struct {
 	Description string
 }
 
+type commandMatch struct {
+	command slashCommand
+	score   int
+}
+
 var slashCommands = []slashCommand{
 	{Name: "/clear", Description: "reset context"},
 	{Name: "/compact", Description: "compress context"},
@@ -132,7 +145,7 @@ var slashCommands = []slashCommand{
 	{Name: "/new", Description: "new session"},
 	{Name: "/status", Description: "show changed files"},
 	{Name: "/diff", Description: "show unstaged diff"},
-	{Name: "/test", Description: "run project tests"},
+	{Name: "/theme", Description: "switch theme light|dark"},
 }
 
 func newModel(ctx context.Context, assistant *agent.Agent, opts Options) model {
@@ -174,6 +187,7 @@ func newModel(ctx context.Context, assistant *agent.Agent, opts Options) model {
 		input:        input,
 		spinner:      spin,
 		status:       "ready",
+		historyIndex: -1,
 	}
 	m.refreshContextUsage()
 	return m
@@ -249,6 +263,20 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				return m, nil
 			}
 			return m.submit()
+		case "ctrl+p":
+			if m.running {
+				return m, nil
+			}
+			m.previousInputHistory()
+			m.afterInputChanged()
+			return m, nil
+		case "ctrl+n":
+			if m.running {
+				return m, nil
+			}
+			m.nextInputHistory()
+			m.afterInputChanged()
+			return m, nil
 		case "alt+enter", "ctrl+j":
 			return m.insertInputNewline()
 		}
@@ -262,8 +290,10 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case toolLogMsg:
 		text := cleanToolLog(string(msg))
 		if text != "" {
+			if !m.mergeToolLog(text) {
 				m.messages = append(m.messages, message{role: roleTool, content: text})
-			m.status = text
+			}
+			m.status = toolStatusText(text)
 			m.refreshViewport(true)
 		}
 		return m, m.waitForEvent()
@@ -297,6 +327,8 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if !m.running {
 			nextInput, cmd := m.input.Update(msg)
 			m.input = nextInput
+			m.historyIndex = -1
+			m.draftInput = ""
 			m.afterInputChanged()
 			return m, cmd
 		}
@@ -343,6 +375,7 @@ func (m *model) submit() (tea.Model, tea.Cmd) {
 	if input == "" {
 		return *m, nil
 	}
+	m.rememberInput(input)
 
 	switch input {
 	case "/exit", "/quit":
@@ -356,7 +389,7 @@ func (m *model) submit() (tea.Model, tea.Cmd) {
 		m.status = "ready"
 		m.refreshViewport(true)
 		return *m, nil
-	case "/model", "/compact":
+	case "/model", "/compact", "/theme":
 		return m.runLocalCommand(input)
 	}
 
@@ -402,6 +435,8 @@ func (m *model) insertInputNewline() (tea.Model, tea.Cmd) {
 	enter := tea.KeyMsg{Type: tea.KeyEnter}
 	nextInput, cmd := m.input.Update(enter)
 	m.input = nextInput
+	m.historyIndex = -1
+	m.draftInput = ""
 	m.afterInputChanged()
 	return *m, cmd
 }
@@ -472,6 +507,10 @@ func (m model) renderMessages() string {
 }
 
 func (m model) messageView(r role, content string, width int) string {
+	if r == roleTool {
+		return m.toolMessageView(content, width)
+	}
+
 	label := roleLabel(r)
 	style := m.styles.AssistantMsg
 	labelStyle := m.styles.SystemLabel
@@ -534,39 +573,169 @@ func roleLabel(r role) string {
 	}
 }
 
+type toolLogParts struct {
+	name   string
+	args   string
+	output string
+}
+
+func parseToolLog(content string) toolLogParts {
+	content = strings.TrimSpace(content)
+	if content == "" {
+		return toolLogParts{}
+	}
+	beforeOutput, output, hasOutput := strings.Cut(content, "\n[output]\n")
+	parts := toolLogParts{}
+	if hasOutput {
+		parts.output = strings.TrimSpace(output)
+	}
+	firstLine := strings.SplitN(beforeOutput, "\n", 2)[0]
+	firstLine = strings.TrimSpace(firstLine)
+	idx := strings.IndexFunc(firstLine, unicode.IsSpace)
+	if idx < 0 {
+		parts.name = firstLine
+		return parts
+	}
+	parts.name = strings.TrimSpace(firstLine[:idx])
+	parts.args = strings.TrimSpace(firstLine[idx+1:])
+	return parts
+}
+
+func (m model) toolMessageView(content string, width int) string {
+	parts := parseToolLog(content)
+	header := m.styles.ToolName.Render(strings.TrimSpace(iconTool + " " + parts.name))
+	lines := []string{header}
+	if parts.args != "" {
+		args := fitLine(parts.args, max(1, width-4))
+		lines = append(lines, m.styles.ToolValue.Render(args))
+	}
+	if parts.output != "" {
+		lines = append(lines, m.styles.ToolKey.Render("output"))
+		previewLines := toolOutputPreviewLines(parts.output, max(1, width-4))
+		for _, line := range previewLines {
+			lines = append(lines, m.styles.ToolValue.Render(line))
+		}
+	}
+	bodyContent := strings.Join(lines, "\n")
+	bodyWidth := messageBodyWidth(bodyContent, width, m.styles.ToolMessage)
+	return m.styles.ToolMessage.Width(bodyWidth).Render(bodyContent)
+}
+
+const maxToolOutputPreviewLines = 8
+
+func toolStatusText(content string) string {
+	content = strings.TrimSpace(content)
+	if content == "" {
+		return ""
+	}
+	lines := strings.SplitN(content, "\n", 2)
+	return lines[0]
+}
+
+func (m *model) mergeToolLog(text string) bool {
+	incoming := parseToolLog(text)
+	if incoming.output == "" {
+		return false
+	}
+	for i := len(m.messages) - 1; i >= 0; i-- {
+		if m.messages[i].role != roleTool {
+			continue
+		}
+		existing := parseToolLog(m.messages[i].content)
+		if existing.name == incoming.name && existing.args == incoming.args && existing.output == "" {
+			m.messages[i].content = text
+			return true
+		}
+	}
+	return false
+}
+
+func toolOutputPreviewLines(output string, width int) []string {
+	lines := strings.Split(output, "\n")
+	if len(lines) > maxToolOutputPreviewLines {
+		lines = lines[:maxToolOutputPreviewLines]
+		lines = append(lines, fmt.Sprintf("[truncated: showing first %d lines]", maxToolOutputPreviewLines))
+	}
+	result := make([]string, 0, len(lines))
+	for _, line := range lines {
+		result = append(result, fitLine(line, width))
+	}
+	return result
+}
+
+type metaPill struct {
+	text   string
+	accent bool
+}
+
+func (m model) renderMetaPills(parts []metaPill) string {
+	if len(parts) == 0 {
+		return ""
+	}
+
+	plain := make([]string, len(parts))
+	for i, part := range parts {
+		plain[i] = part.text
+	}
+
+	width := max(1, m.width-2)
+	visible := len(plain)
+	for visible > 1 && lipgloss.Width(strings.Join(plain[:visible], " ")) > width {
+		visible--
+	}
+	if lipgloss.Width(strings.Join(plain[:visible], " ")) > width {
+		return m.styles.PillAccent.Render(fitLine(plain[0], width))
+	}
+
+	rendered := make([]string, 0, visible)
+	for i := 0; i < visible; i++ {
+		style := m.styles.Pill
+		if parts[i].accent {
+			style = m.styles.PillAccent
+		}
+		rendered = append(rendered, style.Render(parts[i].text))
+	}
+	return strings.Join(rendered, " ")
+}
+
 func (m model) modelMetaView() string {
 	mode := "read-only tools"
 	if m.yolo {
 		mode = "yolo tools"
 	}
+
 	modelName := m.modelName
-	parts := []string{}
 	if m.models != nil {
-		if sessionName := m.models.CurrentSessionName(); sessionName != "" {
-			parts = append(parts, "session "+sessionName)
+		if currentModel := m.models.CurrentModel(); currentModel != "" {
+			modelName = currentModel
 		}
+	}
+
+	parts := []metaPill{{text: iconModel + " " + modelName, accent: true}}
+	if m.models != nil {
 		if provider := m.models.CurrentProvider(); provider != "" {
-			parts = append(parts, "provider "+provider)
+			parts = append(parts, metaPill{text: "provider " + provider})
 		}
-		modelName = m.models.CurrentModel()
 		if currentThinking := m.models.CurrentThinking(); currentThinking != "" && currentThinking != "unset" {
-			parts = append(parts, "thinking "+currentThinking)
+			parts = append(parts, metaPill{text: "thinking " + currentThinking})
+		}
+		if sessionName := m.models.CurrentSessionName(); sessionName != "" {
+			parts = append(parts, metaPill{text: iconSession + " " + sessionName})
 		}
 	}
 	if m.contextUsage != "" {
-		parts = append(parts, m.contextUsage)
+		parts = append(parts, metaPill{text: iconContext + " " + m.contextUsage})
 	}
-	parts = append([]string{modelName, mode}, parts...)
-	parts = append(parts, "theme "+string(m.theme.Mode))
-	line := fitLine(strings.Join(parts, " · "), max(1, m.width-2))
-	return m.styles.ModelMeta.Width(max(1, m.width)).Render(line)
+	parts = append(parts, metaPill{text: mode}, metaPill{text: "theme " + string(m.theme.Mode)})
+
+	return m.styles.ModelMeta.Width(max(1, m.width)).Render(m.renderMetaPills(parts))
 }
 
 func (m model) inputView() string {
-	suggestions := m.slashSuggestionsView()
+	palette := m.commandPaletteView()
 	box := m.styles.InputBox.Width(max(20, m.width-2)).Render(m.input.View())
-	if suggestions != "" {
-		return lipgloss.JoinVertical(lipgloss.Left, suggestions, box)
+	if palette != "" {
+		return lipgloss.JoinVertical(lipgloss.Left, palette, box)
 	}
 	return box
 }
@@ -579,12 +748,12 @@ func (m model) activityView() string {
 	if status == "" || status == "ready" {
 		status = "working..."
 	}
-	line := fitLine(fmt.Sprintf("%s Working · %s · esc cancels", m.spinner.View(), status), max(1, m.width-2))
-	return m.styles.Activity.Width(max(1, m.width)).Render(line)
+	line := m.styles.StatusInfo.Render(iconWorking) + " Working " + m.spinner.View() + " " + status + " · esc cancels"
+	return m.styles.Activity.Render(fitLine(line, max(1, m.width-2)))
 }
 
 func (m model) footerView() string {
-	hint := "enter send · ctrl+j newline · alt+enter newline · / commands"
+	hint := "enter send · ctrl+j newline · alt+enter newline · ctrl+p/ctrl+n history · / commands"
 	if m.running {
 		hint = "esc cancel · ctrl+c quit"
 	}
@@ -639,6 +808,51 @@ func (m *model) afterInputChanged() {
 	}
 }
 
+func (m *model) rememberInput(input string) {
+	input = strings.TrimSpace(input)
+	if input == "" {
+		return
+	}
+	if len(m.inputHistory) > 0 && m.inputHistory[len(m.inputHistory)-1] == input {
+		m.historyIndex = -1
+		m.draftInput = ""
+		return
+	}
+	m.inputHistory = append(m.inputHistory, input)
+	if len(m.inputHistory) > maxInputHistory {
+		m.inputHistory = m.inputHistory[len(m.inputHistory)-maxInputHistory:]
+	}
+	m.historyIndex = -1
+	m.draftInput = ""
+}
+
+func (m *model) previousInputHistory() {
+	if len(m.inputHistory) == 0 {
+		return
+	}
+	if m.historyIndex == -1 {
+		m.draftInput = m.input.Value()
+		m.historyIndex = len(m.inputHistory) - 1
+	} else if m.historyIndex > 0 {
+		m.historyIndex--
+	}
+	m.input.SetValue(m.inputHistory[m.historyIndex])
+}
+
+func (m *model) nextInputHistory() {
+	if len(m.inputHistory) == 0 || m.historyIndex == -1 {
+		return
+	}
+	if m.historyIndex < len(m.inputHistory)-1 {
+		m.historyIndex++
+		m.input.SetValue(m.inputHistory[m.historyIndex])
+		return
+	}
+	m.input.SetValue(m.draftInput)
+	m.historyIndex = -1
+	m.draftInput = ""
+}
+
 func (m *model) syncInputHeight() {
 	m.input.SetHeight(m.desiredInputHeight())
 }
@@ -661,47 +875,132 @@ func (m model) desiredInputHeight() int {
 
 func (m model) inputBlockHeight() int {
 	height := m.input.Height() + m.styles.InputBox.GetVerticalFrameSize()
-	if m.showSlashSuggestions() {
-		height += m.slashSuggestionCount()
+	if m.showCommandPalette() {
+		height += m.commandPaletteHeight()
 	}
 	return height
 }
 
-func (m model) slashSuggestionCount() int {
-	prefix := strings.TrimSpace(m.input.Value())
-	count := 0
-	for _, command := range slashCommands {
-		if strings.HasPrefix(command.Name, prefix) {
-			count++
-		}
+func (m model) commandPaletteHeight() int {
+	matches := commandMatches(commandPaletteQuery(m.input.Value()))
+	count := len(matches)
+	if count > maxCommandPaletteItems {
+		count = maxCommandPaletteItems
 	}
 	if count == 0 {
-		count = 1 // "No matching commands"
+		count = 1
 	}
-	return count
+	return 1 + count + m.styles.Palette.GetVerticalFrameSize()
 }
 
-func (m model) showSlashSuggestions() bool {
+func (m model) showCommandPalette() bool {
 	value := strings.TrimSpace(m.input.Value())
 	return strings.HasPrefix(value, "/") && !strings.Contains(value, " ")
 }
 
-func (m model) slashSuggestionsView() string {
-	if !m.showSlashSuggestions() {
+func (m model) commandPaletteView() string {
+	if !m.showCommandPalette() {
 		return ""
 	}
-	prefix := strings.TrimSpace(m.input.Value())
-	var parts []string
+	matches := commandMatches(commandPaletteQuery(m.input.Value()))
+	lines := []string{m.styles.Header.Render(iconCommand + " Commands")}
+	if len(matches) == 0 {
+		lines = append(lines, m.styles.Muted.Render("No matching commands"))
+	} else {
+		for i, match := range matches {
+			if i >= maxCommandPaletteItems {
+				break
+			}
+			lines = append(lines, fmt.Sprintf("%s %s", m.styles.PaletteMatch.Render(match.command.Name), m.styles.Muted.Render(match.command.Description)))
+		}
+	}
+	return m.styles.Palette.Width(max(20, m.width-2)).Render(strings.Join(lines, "\n"))
+}
+
+func commandPaletteQuery(value string) string {
+	value = strings.TrimSpace(value)
+	if !strings.HasPrefix(value, "/") {
+		return ""
+	}
+	return strings.TrimPrefix(value, "/")
+}
+
+func commandMatches(query string) []commandMatch {
+	matches := make([]commandMatch, 0, len(slashCommands))
 	for _, command := range slashCommands {
-		if !strings.HasPrefix(command.Name, prefix) {
+		score, ok := scoreCommand(command, query)
+		if !ok {
 			continue
 		}
-		parts = append(parts, fmt.Sprintf("%s %s", command.Name, command.Description))
+		matches = append(matches, commandMatch{command: command, score: score})
 	}
-	if len(parts) == 0 {
-		parts = append(parts, "No matching commands")
+	sort.Slice(matches, func(i, j int) bool {
+		if matches[i].score != matches[j].score {
+			return matches[i].score < matches[j].score
 		}
-	return m.styles.CommandHint.Width(max(20, m.width-2)).Render(strings.Join(parts, "\n"))
+		return matches[i].command.Name < matches[j].command.Name
+	})
+	return matches
+}
+
+func scoreCommand(command slashCommand, query string) (int, bool) {
+	query = strings.ToLower(strings.TrimSpace(query))
+	name := strings.TrimPrefix(strings.ToLower(command.Name), "/")
+	if query == "" || query == name {
+		return 0, true
+	}
+	if strings.HasPrefix(name, query) {
+		return 100 + len(name) - len(query), true
+	}
+	if score, ok := subsequenceScore(name, query, 200); ok {
+		return score, true
+	}
+	candidate := name + " " + strings.ToLower(command.Description)
+	if score, ok := subsequenceScore(candidate, query, 300); ok {
+		return score, true
+	}
+	return 0, false
+}
+
+func subsequenceScore(candidate string, query string, base int) (int, bool) {
+	candidate = strings.ToLower(candidate)
+	query = strings.ToLower(query)
+	if query == "" {
+		return base, true
+	}
+	start := 0
+	last := -1
+	gaps := 0
+	for _, r := range query {
+		found := -1
+		for i, c := range candidate[start:] {
+			if c == r {
+				found = start + i
+				break
+			}
+		}
+		if found < 0 {
+			return 0, false
+		}
+		if last >= 0 {
+			gaps += found - last - 1
+		}
+		last = found
+		start = found + len(string(r))
+	}
+	return base + gaps, true
+}
+
+func (m model) slashSuggestionCount() int {
+	return m.commandPaletteHeight()
+}
+
+func (m model) showSlashSuggestions() bool {
+	return m.showCommandPalette()
+}
+
+func (m model) slashSuggestionsView() string {
+	return m.commandPaletteView()
 }
 
 func (m model) modelInfo() string {
@@ -791,6 +1090,9 @@ func fitLine(text string, width int) string {
 }
 
 func (m *model) runLocalCommand(input string) (tea.Model, tea.Cmd) {
+	if strings.HasPrefix(input, "/theme") {
+		return m.handleThemeCommand(input)
+	}
 	output, err := m.handleLocalCommand(input)
 	if err == errOpenPicker {
 		m.openSessionPicker()
@@ -815,6 +1117,35 @@ func (m *model) runLocalCommand(input string) (tea.Model, tea.Cmd) {
 	return *m, nil
 }
 
+func (m *model) handleThemeCommand(input string) (tea.Model, tea.Cmd) {
+	fields := strings.Fields(input)
+	if len(fields) < 2 {
+		m.input.SetValue("")
+		m.afterInputChanged()
+		m.messages = append(m.messages, message{
+			role: roleSystem, content: "theme: " + string(m.theme.Mode) + "\nusage: /theme light|dark",
+		})
+		m.refreshViewport(true)
+		return *m, nil
+	}
+	mode, err := ParseThemeMode(fields[1])
+	if err != nil {
+		m.input.SetValue("")
+		m.afterInputChanged()
+		m.messages = append(m.messages, message{role: roleError, content: err.Error()})
+		m.refreshViewport(true)
+		return *m, nil
+	}
+	m.theme = themeForMode(mode)
+	m.styles = m.theme.styles()
+	applyTextareaTheme(&m.input, m.theme)
+	m.input.SetValue("")
+	m.afterInputChanged()
+	m.messages = append(m.messages, message{role: roleSystem, content: "theme: " + string(mode)})
+	m.refreshViewport(true)
+	return *m, nil
+}
+
 func (m model) handleLocalCommand(input string) (string, error) {
 	fields := strings.Fields(input)
 	if len(fields) == 0 {

internal/tui/app_test.go

@@ -9,7 +9,7 @@ import (
 	"testing"
 
 	"agentu/internal/agent"
-	"agentu/internal/llm"
+	"agentu/pkg/llm"
 
 	tea "github.com/charmbracelet/bubbletea"
 	"github.com/charmbracelet/lipgloss"
@@ -21,7 +21,7 @@ func TestModelRendersChatShell(t *testing.T) {
 	m = next.(model)
 	rendered := m.View()
 
-	for _, want := range []string{"test-model", "yolo tools", "light", "ctrl+j", "alt+enter"} {
+	for _, want := range []string{"test-model", "yolo tools", "light", "ctrl+j", "alt+enter", "ctrl+p/ctrl+n history"} {
 		if !strings.Contains(rendered, want) {
 			t.Fatalf("rendered view missing %q:\n%s", want, rendered)
 		}
@@ -123,11 +123,14 @@ func TestRunningStateRendersActivityIndicator(t *testing.T) {
 	m.resize()
 
 	rendered := m.View()
-	for _, want := range []string{"Working", "thinking...", "esc cancels"} {
+	for _, want := range []string{iconWorking, "Working", "thinking...", "esc cancels"} {
 		if !strings.Contains(rendered, want) {
 			t.Fatalf("running view missing %q:\n%s", want, rendered)
 		}
 	}
+	if backgroundPattern.MatchString(m.activityView()) {
+		t.Fatalf("activity view should not paint a background:\n%q", m.activityView())
+	}
 }
 
 func TestUserMessageRendersFullWidthBubble(t *testing.T) {
@@ -276,19 +279,110 @@ func TestInputStartsAtOneLineAndGrows(t *testing.T) {
 	}
 }
 
-func TestSlashCommandSuggestions(t *testing.T) {
+func TestCommandPaletteFuzzyMatches(t *testing.T) {
 	m := newModel(context.Background(), nil, Options{ModelName: "test-model", Yolo: true})
 	next, _ := m.Update(tea.WindowSizeMsg{Width: 100, Height: 30})
 	m = next.(model)
-	m.input.SetValue("/")
+	m.input.SetValue("/mdl")
 	m.afterInputChanged()
 
-	rendered := m.View()
-	for _, want := range []string{"/clear reset context", "/compact compress context", "/exit quit", "/model model/provider/thinking"} {
-		if !strings.Contains(rendered, want) {
-			t.Fatalf("rendered suggestions missing %q:\n%s", want, rendered)
+	plain := stripANSI(m.View())
+	for _, want := range []string{iconCommand + " Commands", "/model model/provider/thinking"} {
+		if !strings.Contains(plain, want) {
+			t.Fatalf("rendered palette missing %q:\n%s", want, plain)
 		}
 	}
+
+	matches := commandMatches("m")
+	modelIndex := -1
+	renameIndex := -1
+	for i, match := range matches {
+		switch match.command.Name {
+		case "/model":
+			modelIndex = i
+		case "/rename":
+			renameIndex = i
+		}
+	}
+	if modelIndex < 0 || renameIndex < 0 || modelIndex > renameIndex {
+		t.Fatalf("/model should sort before /rename for /m query: %#v", matches)
+	}
+}
+
+func TestInputHistoryNavigation(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model"})
+	m.rememberInput("first")
+	m.rememberInput("second")
+
+	next, _ := m.Update(tea.KeyMsg{Type: tea.KeyCtrlP})
+	m = next.(model)
+	if got := m.input.Value(); got != "second" {
+		t.Fatalf("after ctrl+p input = %q", got)
+	}
+	next, _ = m.Update(tea.KeyMsg{Type: tea.KeyCtrlP})
+	m = next.(model)
+	if got := m.input.Value(); got != "first" {
+		t.Fatalf("after second ctrl+p input = %q", got)
+	}
+	next, _ = m.Update(tea.KeyMsg{Type: tea.KeyCtrlN})
+	m = next.(model)
+	if got := m.input.Value(); got != "second" {
+		t.Fatalf("after ctrl+n input = %q", got)
+	}
+	next, _ = m.Update(tea.KeyMsg{Type: tea.KeyCtrlN})
+	m = next.(model)
+	if got := m.input.Value(); got != "" {
+		t.Fatalf("after second ctrl+n input = %q", got)
+	}
+}
+
+func TestToolMessageRendersStructuredCard(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model"})
+	m.messages = append(m.messages, message{role: roleTool, content: `file_read {"path":"README.md"}`})
+
+	plain := stripANSI(m.renderMessages())
+	for _, want := range []string{iconTool + " file_read", "README.md"} {
+		if !strings.Contains(plain, want) {
+			t.Fatalf("tool card missing %q:\n%s", want, plain)
+		}
+	}
+}
+
+func TestToolMessageRendersOutputPreview(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model"})
+	m.messages = append(m.messages, message{role: roleTool, content: "file_read {\"path\":\"README.md\"}\n[output]\nfirst line\nsecond line"})
+
+	plain := stripANSI(m.renderMessages())
+	for _, want := range []string{iconTool + " file_read", "README.md", "output", "first line", "second line"} {
+		if !strings.Contains(plain, want) {
+			t.Fatalf("tool card missing %q:\n%s", want, plain)
+		}
+	}
+}
+
+func TestToolLogOutputUpdatesExistingToolCard(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model"})
+	m.messages = append(m.messages, message{role: roleTool, content: `file_read {"path":"README.md"}`})
+
+	updated := m.mergeToolLog("file_read {\"path\":\"README.md\"}\n[output]\nhello")
+	if !updated {
+		t.Fatal("expected mergeToolLog to return true")
+	}
+	if len(m.messages) != 1 {
+		t.Fatalf("messages count = %d, want 1", len(m.messages))
+	}
+	plain := stripANSI(m.renderMessages())
+	if !strings.Contains(plain, "hello") {
+		t.Fatalf("rendered output missing 'hello':\n%s", plain)
+	}
+
+	status := toolStatusText("file_read {\"path\":\"README.md\"}\n[output]\nhello world")
+	if strings.Contains(status, "hello") {
+		t.Fatalf("status should not contain output: %q", status)
+	}
+	if !strings.Contains(status, "file_read") {
+		t.Fatalf("status missing tool name: %q", status)
+	}
 }
 
 type tuiCompactProvider struct{}
@@ -510,6 +604,115 @@ func TestParseThemeMode(t *testing.T) {
 	}
 }
 
+func requireStyleColor(t *testing.T, name string, got lipgloss.TerminalColor, want string) {
+	t.Helper()
+	color, ok := got.(lipgloss.Color)
+	if !ok {
+		t.Fatalf("%s = %T, want lipgloss.Color", name, got)
+	}
+	if string(color) != want {
+		t.Fatalf("%s = %q, want %q", name, string(color), want)
+	}
+}
+
+func requireNoStyleColor(t *testing.T, name string, got lipgloss.TerminalColor) {
+	t.Helper()
+	if _, ok := got.(lipgloss.NoColor); !ok {
+		t.Fatalf("%s should not paint a color, got %T", name, got)
+	}
+}
+
+func TestDarkThemePaintsAppBackground(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model", ThemeMode: ThemeDark})
+	next, _ := m.Update(tea.WindowSizeMsg{Width: 100, Height: 30})
+	m = next.(model)
+	rendered := stripANSI(m.View())
+	if !strings.Contains(rendered, "theme dark") {
+		t.Fatalf("rendered view missing 'theme dark':\n%s", rendered)
+	}
+	if m.theme.Mode != ThemeDark {
+		t.Fatalf("theme.Mode = %q, want %q", m.theme.Mode, ThemeDark)
+	}
+	want := darkTheme()
+	requireStyleColor(t, "App.Background", m.styles.App.GetBackground(), want.Background)
+	requireStyleColor(t, "App.Foreground", m.styles.App.GetForeground(), want.Text)
+}
+
+func TestDarkThemeKeepsComponentBackgroundsLightweight(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model", ThemeMode: ThemeDark})
+	next, _ := m.Update(tea.WindowSizeMsg{Width: 100, Height: 30})
+	m = next.(model)
+	requireNoStyleColor(t, "Viewport.Background", m.styles.Viewport.GetBackground())
+	requireNoStyleColor(t, "InputBox.Background", m.styles.InputBox.GetBackground())
+	requireNoStyleColor(t, "AssistantMsg.Background", m.styles.AssistantMsg.GetBackground())
+	requireNoStyleColor(t, "Activity.Background", m.styles.Activity.GetBackground())
+	m.running = true
+	m.status = "thinking..."
+	m.resize()
+	if backgroundPattern.MatchString(m.activityView()) {
+		t.Fatalf("activity view should not paint a background:\n%q", m.activityView())
+	}
+}
+
+func TestDarkThemeStylesUseDarkPalette(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model", ThemeMode: ThemeDark})
+	want := darkTheme()
+	requireStyleColor(t, "Header.Foreground", m.styles.Header.GetForeground(), want.Title)
+	requireStyleColor(t, "Muted.Foreground", m.styles.Muted.GetForeground(), want.Muted)
+	requireStyleColor(t, "Pill.Background", m.styles.Pill.GetBackground(), want.SurfaceAlt)
+	requireStyleColor(t, "input.FocusedStyle.Base.Foreground", m.input.FocusedStyle.Base.GetForeground(), want.Text)
+	requireStyleColor(t, "input.FocusedStyle.Placeholder.Foreground", m.input.FocusedStyle.Placeholder.GetForeground(), want.Muted)
+}
+
+func TestModelCommandShowsDarkTheme(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model", ThemeMode: ThemeDark})
+	m.input.SetValue("/model")
+	next, _ := m.submit()
+	rendered := next.(model).renderMessages()
+	if !strings.Contains(rendered, "theme: dark") {
+		t.Fatalf("model command output missing 'theme: dark':\n%s", rendered)
+	}
+}
+
+func TestThemeSlashCommandSwitchesAtRuntime(t *testing.T) {
+	m := newModel(context.Background(), nil, Options{ModelName: "test-model"})
+	if m.theme.Mode != ThemeLight {
+		t.Fatalf("initial theme = %q, want light", m.theme.Mode)
+	}
+	requireNoStyleColor(t, "initial App.Background", m.styles.App.GetBackground())
+
+	// Switch to dark
+	m.input.SetValue("/theme dark")
+	next, _ := m.submit()
+	m = next.(model)
+	if m.theme.Mode != ThemeDark {
+		t.Fatalf("after /theme dark: Mode = %q, want dark", m.theme.Mode)
+	}
+	requireStyleColor(t, "dark App.Background", m.styles.App.GetBackground(), darkTheme().Background)
+	last := m.messages[len(m.messages)-1]
+	if !strings.Contains(last.content, "theme: dark") {
+		t.Fatalf("expected confirmation message, got %q", last.content)
+	}
+
+	// Switch back to light
+	m.input.SetValue("/theme light")
+	next, _ = m.submit()
+	m = next.(model)
+	if m.theme.Mode != ThemeLight {
+		t.Fatalf("after /theme light: Mode = %q, want light", m.theme.Mode)
+	}
+	requireNoStyleColor(t, "restored App.Background", m.styles.App.GetBackground())
+
+	// No arg shows usage
+	m.input.SetValue("/theme")
+	next, _ = m.submit()
+	m = next.(model)
+	last = m.messages[len(m.messages)-1]
+	if !strings.Contains(last.content, "usage: /theme") {
+		t.Fatalf("expected usage hint, got %q", last.content)
+	}
+}
+
 func TestCleanToolLog(t *testing.T) {
 	got := cleanToolLog("\n[tool] shell_run {\"command\":\"pwd\"}\n")
 	want := `shell_run {"command":"pwd"}`

internal/tui/theme.go

@@ -15,6 +15,17 @@ const (
 	ThemeDark  ThemeMode = "dark"
 )
 
+const (
+	iconReady   = "✓"
+	iconWorking = "◆"
+	iconTool    = "▣"
+	iconError   = "✕"
+	iconCommand = "⌘"
+	iconSession = "◌"
+	iconContext = "◔"
+	iconModel   = "◉"
+)
+
 func ParseThemeMode(value string) (ThemeMode, error) {
 	switch ThemeMode(strings.ToLower(strings.TrimSpace(value))) {
 	case "", ThemeLight:
@@ -48,11 +59,23 @@ type styles struct {
 	App           lipgloss.Style
 	Muted         lipgloss.Style
 	Activity      lipgloss.Style
+	Header        lipgloss.Style
 	ModelMeta     lipgloss.Style
 	Footer        lipgloss.Style
 	Viewport      lipgloss.Style
 	InputBox      lipgloss.Style
 	CommandHint   lipgloss.Style
+	StatusReady   lipgloss.Style
+	StatusWarn    lipgloss.Style
+	StatusError   lipgloss.Style
+	StatusInfo    lipgloss.Style
+	Pill          lipgloss.Style
+	PillAccent    lipgloss.Style
+	Palette       lipgloss.Style
+	PaletteMatch  lipgloss.Style
+	ToolName      lipgloss.Style
+	ToolKey       lipgloss.Style
+	ToolValue     lipgloss.Style
 	UserLabel     lipgloss.Style
 	ToolLabel     lipgloss.Style
 	ErrorLabel    lipgloss.Style
@@ -107,23 +130,31 @@ func darkTheme() theme {
 	}
 }
 
+func appStyle(t theme) lipgloss.Style {
+	style := lipgloss.NewStyle().Foreground(lipgloss.Color(t.Text))
+	if t.Mode == ThemeDark {
+		style = style.Background(lipgloss.Color(t.Background))
+	}
+	return style
+}
+
 func (t theme) styles() styles {
 	return styles{
-		App: lipgloss.NewStyle().
-			Foreground(lipgloss.Color(t.Text)),
+		App: appStyle(t),
 
 		Muted: lipgloss.NewStyle().
 			Foreground(lipgloss.Color(t.Muted)),
 
 		Activity: lipgloss.NewStyle().
-			Bold(true).
-			Foreground(lipgloss.Color(t.Background)).
-			Background(lipgloss.Color(t.Title)).
+			Foreground(lipgloss.Color(t.Muted)).
 			Padding(0, 1),
 
+		Header: lipgloss.NewStyle().
+			Bold(true).
+			Foreground(lipgloss.Color(t.Title)),
+
 		ModelMeta: lipgloss.NewStyle().
-			Foreground(lipgloss.Color(t.Text)).
-			Background(lipgloss.Color(t.SurfaceAlt)).
+			Foreground(lipgloss.Color(t.Muted)).
 			Padding(0, 1),
 
 		Footer: lipgloss.NewStyle().
@@ -141,9 +172,51 @@ func (t theme) styles() styles {
 
 		CommandHint: lipgloss.NewStyle().
 			Foreground(lipgloss.Color(t.Muted)).
+			Padding(0, 1),
+
+		StatusReady: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.Assistant)),
+
+		StatusWarn: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.Tool)),
+
+		StatusError: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.Error)),
+
+		StatusInfo: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.User)),
+
+		Pill: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.Text)).
 			Background(lipgloss.Color(t.SurfaceAlt)).
 			Padding(0, 1),
 
+		PillAccent: lipgloss.NewStyle().
+			Bold(true).
+			Foreground(lipgloss.Color(t.Title)).
+			Background(lipgloss.Color(t.SurfaceAlt)).
+			Padding(0, 1),
+
+		Palette: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.Text)).
+			Border(lipgloss.ThickBorder()).
+			BorderForeground(lipgloss.Color(t.Border)).
+			Padding(0, 2),
+
+		PaletteMatch: lipgloss.NewStyle().
+			Bold(true).
+			Foreground(lipgloss.Color(t.User)),
+
+		ToolName: lipgloss.NewStyle().
+			Bold(true).
+			Foreground(lipgloss.Color(t.Tool)),
+
+		ToolKey: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.Muted)),
+
+		ToolValue: lipgloss.NewStyle().
+			Foreground(lipgloss.Color(t.Text)),
+
 		UserLabel:   labelStyle(t.User),
 		ToolLabel:   labelStyle(t.Tool),
 		ErrorLabel:  labelStyle(t.Error),

main.go

@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"agentu/internal/app"
+)
+
+func main() {
+	if err := app.Run(); err != nil {
+		fmt.Fprintln(os.Stderr, "agentu:", err)
+		os.Exit(1)
+	}
+}