wip: P1 feature batch — retry, search, code symbols, diff/status/test commands, tool output head+tail

- retry logic for transient LLM errors (openai.go)
- file_search context_lines + max_results (file.go)
- FormatResult now preserves head+tail with omitted bytes (tools.go)
- /status /diff /test slash commands wired (workflow.go, app.go)
- CodeSymbolsTool for Go package/type/func listing (code.go)
- README updated with v0.0.4 features

internal/tools/code.go

@@ -0,0 +1,219 @@
+package tools
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/printer"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"agentu/internal/llm"
+)
+
+const defaultCodeSymbolFileLimit = 50
+
+type CodeSymbolsTool struct {
+	workingDir string
+}
+
+func NewCodeSymbolsTool(workingDir string) *CodeSymbolsTool {
+	return &CodeSymbolsTool{workingDir: workingDir}
+}
+
+func (t *CodeSymbolsTool) Definition() llm.Tool {
+	return llm.Tool{
+		Type: "function",
+		Function: llm.ToolFunction{
+			Name:        "code_symbols",
+			Description: "List Go code symbols (packages, imports, types, functions, methods) for a file or directory without reading full file contents.",
+			Parameters: JSONSchema(`{
+  "type": "object",
+  "properties": {
+    "path": {"type": "string", "description": "Go file or directory to inspect. Defaults to the configured agent working directory."},
+    "max_files": {"type": "integer", "description": "Maximum number of Go files to inspect when path is a directory. Defaults to 50."}
+  },
+  "additionalProperties": false
+}`),
+		},
+	}
+}
+
+type codeSymbolsArgs struct {
+	Path     string `json:"path"`
+	MaxFiles int    `json:"max_files"`
+}
+
+func (t *CodeSymbolsTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
+	var args codeSymbolsArgs
+	if err := json.Unmarshal(raw, &args); err != nil {
+		return "", fmt.Errorf("parse arguments: %w", err)
+	}
+	path, err := resolvePath(t.workingDir, args.Path)
+	if err != nil {
+		return "", err
+	}
+	limit := args.MaxFiles
+	if limit <= 0 {
+		limit = defaultCodeSymbolFileLimit
+	}
+
+	files, err := goFiles(ctx, path, limit)
+	if err != nil {
+		return "", err
+	}
+	if len(files) == 0 {
+		return "no Go files found", nil
+	}
+
+	fset := token.NewFileSet()
+	var out strings.Builder
+	for i, file := range files {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return FormatResult(out.String()), ctxErr
+		}
+		if i > 0 {
+			out.WriteString("\n")
+		}
+		if err := appendGoSymbols(&out, fset, file); err != nil {
+			fmt.Fprintf(&out, "%s\nerror: %v\n", file, err)
+		}
+		if out.Len() > MaxToolOutputBytes {
+			break
+		}
+	}
+	return FormatResult(out.String()), nil
+}
+
+func goFiles(ctx context.Context, path string, limit int) ([]string, error) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return nil, err
+	}
+	if !info.IsDir() {
+		if strings.HasSuffix(path, ".go") {
+			return []string{path}, nil
+		}
+		return nil, fmt.Errorf("path is not a Go file: %s", path)
+	}
+
+	var files []string
+	stop := errors.New("file limit reached")
+	err = filepath.WalkDir(path, func(current string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return nil
+		}
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return ctxErr
+		}
+		if d.IsDir() {
+			switch d.Name() {
+			case ".git", "vendor", "node_modules":
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if strings.HasSuffix(current, ".go") {
+			files = append(files, current)
+			if len(files) >= limit {
+				return stop
+			}
+		}
+		return nil
+	})
+	if err != nil && !errors.Is(err, stop) {
+		return nil, err
+	}
+	sort.Strings(files)
+	return files, nil
+}
+
+func appendGoSymbols(out *strings.Builder, fset *token.FileSet, path string) error {
+	file, err := parser.ParseFile(fset, path, nil, parser.ImportsOnly|parser.ParseComments)
+	if err != nil {
+		return err
+	}
+	full, err := parser.ParseFile(fset, path, nil, 0)
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(out, "%s\n", path)
+	fmt.Fprintf(out, "  package %s\n", full.Name.Name)
+	if len(file.Imports) > 0 {
+		imports := make([]string, 0, len(file.Imports))
+		for _, imp := range file.Imports {
+			imports = append(imports, strings.Trim(imp.Path.Value, "\""))
+		}
+		fmt.Fprintf(out, "  imports: %s\n", strings.Join(imports, ", "))
+	}
+
+	var types, funcs, methods []string
+	for _, decl := range full.Decls {
+		switch d := decl.(type) {
+		case *ast.GenDecl:
+			if d.Tok != token.TYPE {
+				continue
+			}
+			for _, spec := range d.Specs {
+				if ts, ok := spec.(*ast.TypeSpec); ok {
+					kind := typeKind(ts.Type)
+					types = append(types, fmt.Sprintf("%d: type %s %s", fset.Position(ts.Pos()).Line, ts.Name.Name, kind))
+				}
+			}
+		case *ast.FuncDecl:
+			line := fset.Position(d.Pos()).Line
+			if d.Recv == nil {
+				funcs = append(funcs, fmt.Sprintf("%d: func %s", line, d.Name.Name))
+				continue
+			}
+			methods = append(methods, fmt.Sprintf("%d: method %s.%s", line, receiverName(d.Recv), d.Name.Name))
+		}
+	}
+	appendSymbolGroup(out, "types", types)
+	appendSymbolGroup(out, "funcs", funcs)
+	appendSymbolGroup(out, "methods", methods)
+	return nil
+}
+
+func appendSymbolGroup(out *strings.Builder, title string, values []string) {
+	if len(values) == 0 {
+		return
+	}
+	fmt.Fprintf(out, "  %s:\n", title)
+	for _, value := range values {
+		fmt.Fprintf(out, "    - %s\n", value)
+	}
+}
+
+func typeKind(expr ast.Expr) string {
+	switch expr.(type) {
+	case *ast.StructType:
+		return "struct"
+	case *ast.InterfaceType:
+		return "interface"
+	case *ast.FuncType:
+		return "func"
+	default:
+		return "alias"
+	}
+}
+
+func receiverName(recv *ast.FieldList) string {
+	if recv == nil || len(recv.List) == 0 {
+		return "?"
+	}
+	var b bytes.Buffer
+	if err := printer.Fprint(&b, token.NewFileSet(), recv.List[0].Type); err != nil {
+		return "?"
+	}
+	return b.String()
+}

internal/tools/file.go

@@ -223,7 +223,9 @@ func (t *FileSearchTool) Definition() llm.Tool {
   "properties": {
     "query": {"type": "string", "description": "Text or regular expression to search for."},
     "path": {"type": "string", "description": "Optional directory or file to search. Defaults to the configured agent working directory."},
-    "glob": {"type": "string", "description": "Optional file glob, for example '*.go'."}
+    "glob": {"type": "string", "description": "Optional file glob, for example '*.go'."},
+    "context_lines": {"type": "integer", "description": "Optional number of context lines around each match. Defaults to 0."},
+    "max_results": {"type": "integer", "description": "Optional maximum matches to return. Defaults to 100."}
   },
   "required": ["query"],
   "additionalProperties": false
@@ -233,9 +235,11 @@ func (t *FileSearchTool) Definition() llm.Tool {
 }
 
 type fileSearchArgs struct {
-	Query string `json:"query"`
-	Path  string `json:"path"`
-	Glob  string `json:"glob"`
+	Query        string `json:"query"`
+	Path         string `json:"path"`
+	Glob         string `json:"glob"`
+	ContextLines int    `json:"context_lines"`
+	MaxResults   int    `json:"max_results"`
 }
 
 func (t *FileSearchTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
@@ -256,8 +260,31 @@ func (t *FileSearchTool) Execute(ctx context.Context, raw json.RawMessage) (stri
 	return t.walkSearch(ctx, args, path)
 }
 
+func normalizedSearchOptions(args fileSearchArgs) (contextLines int, maxResults int) {
+	contextLines = args.ContextLines
+	if contextLines < 0 {
+		contextLines = 0
+	}
+	if contextLines > 5 {
+		contextLines = 5
+	}
+	maxResults = args.MaxResults
+	if maxResults <= 0 {
+		maxResults = 100
+	}
+	if maxResults > 1000 {
+		maxResults = 1000
+	}
+	return contextLines, maxResults
+}
+
 func (t *FileSearchTool) ripgrep(ctx context.Context, args fileSearchArgs, path string) (string, error) {
 	rgArgs := []string{"--line-number", "--color", "never"}
+	contextLines, maxResults := normalizedSearchOptions(args)
+	if contextLines > 0 {
+		rgArgs = append(rgArgs, "--context", fmt.Sprint(contextLines))
+	}
+	rgArgs = append(rgArgs, "--max-count", fmt.Sprint(maxResults))
 	if args.Glob != "" {
 		rgArgs = append(rgArgs, "--glob", args.Glob)
 	}
@@ -282,7 +309,10 @@ func (t *FileSearchTool) ripgrep(ctx context.Context, args fileSearchArgs, path
 }
 
 func (t *FileSearchTool) walkSearch(ctx context.Context, args fileSearchArgs, root string) (string, error) {
+	contextLines, maxResults := normalizedSearchOptions(args)
 	var out bytes.Buffer
+	matchCount := 0
+	stop := errors.New("result limit reached")
 	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
 		if err != nil {
 			return nil
@@ -312,16 +342,22 @@ func (t *FileSearchTool) walkSearch(ctx context.Context, args fileSearchArgs, ro
 		}
 		lines := strings.Split(string(data), "\n")
 		for i, line := range lines {
-			if strings.Contains(line, args.Query) {
-				fmt.Fprintf(&out, "%s:%d:%s\n", path, i+1, line)
-				if out.Len() > MaxToolOutputBytes {
-					return errors.New("output limit reached")
-				}
+			if !strings.Contains(line, args.Query) {
+				continue
+			}
+			matchCount++
+			appendSearchMatch(&out, path, lines, i, contextLines)
+			if matchCount >= maxResults {
+				fmt.Fprintf(&out, "[stopped after %d matches; narrow path/query or raise max_results]\n", maxResults)
+				return stop
+			}
+			if out.Len() > MaxToolOutputBytes {
+				return stop
 			}
 		}
 		return nil
 	})
-	if err != nil && err.Error() != "output limit reached" {
+	if err != nil && !errors.Is(err, stop) {
 		return "", err
 	}
 	if out.Len() == 0 {
@@ -329,3 +365,18 @@ func (t *FileSearchTool) walkSearch(ctx context.Context, args fileSearchArgs, ro
 	}
 	return FormatResult(out.String()), nil
 }
+
+func appendSearchMatch(out *bytes.Buffer, path string, lines []string, matchIndex int, contextLines int) {
+	start := max(0, matchIndex-contextLines)
+	end := min(len(lines)-1, matchIndex+contextLines)
+	if contextLines > 0 {
+		fmt.Fprintf(out, "-- %s:%d --\n", path, matchIndex+1)
+	}
+	for i := start; i <= end; i++ {
+		marker := ":"
+		if i == matchIndex {
+			marker = "*"
+		}
+		fmt.Fprintf(out, "%s%s%d:%s\n", path, marker, i+1, lines[i])
+	}
+}

internal/tools/tools.go

@@ -5,12 +5,15 @@ import (
 	"encoding/json"
 	"fmt"
 	"sort"
+	"strings"
 
 	"agentu/internal/llm"
 )
 
 const MaxToolOutputBytes = 64 * 1024
 
+const truncationNoticeBudget = 160
+
 type Tool interface {
 	Definition() llm.Tool
 	Execute(ctx context.Context, args json.RawMessage) (string, error)
@@ -62,11 +65,13 @@ func ReadOnlyBuiltins(workingDir string) *Registry {
 	fileRead := NewFileReadTool(workingDir)
 	fileList := NewFileListTool(workingDir)
 	fileSearch := NewFileSearchTool(workingDir)
+	codeSymbols := NewCodeSymbolsTool(workingDir)
 
-	registry := NewRegistry(fileRead, fileList, fileSearch)
+	registry := NewRegistry(fileRead, fileList, fileSearch, codeSymbols)
 	registry.RegisterAlias("file.read", fileRead)
 	registry.RegisterAlias("file.list", fileList)
 	registry.RegisterAlias("file.search", fileSearch)
+	registry.RegisterAlias("code.symbols", codeSymbols)
 	return registry
 }
 
@@ -83,8 +88,8 @@ func Builtins(workingDir string) *Registry {
 
 func AgentInstructions(workingDir string, yolo bool) string {
 	searchInstructions := webSearchInstructions()
-	readOnlyTools := "file_list, file_read, file_search, web_search, web_fetch"
-	yoloTools := "file_list, file_read, file_search, file_write, shell_run, web_search, web_fetch"
+	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"
 	if yolo {
 		return fmt.Sprintf(`Local project context:
 - The project working directory is %q.
@@ -92,6 +97,7 @@ func AgentInstructions(workingDir string, yolo bool) string {
 - Do not call tools for greetings, small talk, simple Q&A, or general questions that do not require local project or command context.
 - Do not explore the project preemptively. Do not call file_list just to discover context unless the user asks about project files or the answer truly depends on local files.
 - 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.
 - Do not use file tools as a substitute for a command execution request.
 - Do not start interactive or long-running sessions. Prefer bounded, non-interactive local commands with clear completion conditions.
@@ -105,6 +111,7 @@ func AgentInstructions(workingDir string, yolo bool) string {
 - Do not call tools for greetings, small talk, simple Q&A, or general questions that do not require local project context.
 - Do not explore the project preemptively. Do not call file_list just to discover context unless the user asks about project files or the answer truly depends on local files.
 - 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.
 - %s
 - Tool paths should normally be relative to the project working directory.
@@ -120,10 +127,40 @@ func JSONSchema(schema string) json.RawMessage {
 }
 
 func FormatResult(output string) string {
-	if len(output) <= MaxToolOutputBytes {
+	return FormatResultLimit(output, MaxToolOutputBytes)
+}
+
+func FormatResultLimit(output string, limit int) string {
+	if limit <= 0 || len(output) <= limit {
 		return output
 	}
-	return output[:MaxToolOutputBytes] + fmt.Sprintf("\n\n[truncated after %d bytes]", MaxToolOutputBytes)
+	if limit <= truncationNoticeBudget {
+		return output[:limit]
+	}
+	notice := fmt.Sprintf("\n\n[truncated: showing head and tail; omitted %d bytes]\n\n", len(output)-limit)
+	keep := limit - len(notice)
+	if keep <= 0 {
+		return output[:limit]
+	}
+	headLen := keep / 2
+	tailLen := keep - headLen
+	head := trimHeadAtLine(output[:headLen])
+	tail := trimTailAtLine(output[len(output)-tailLen:])
+	return head + notice + tail
+}
+
+func trimHeadAtLine(value string) string {
+	if idx := strings.LastIndexByte(value, '\n'); idx > 0 {
+		return value[:idx+1]
+	}
+	return value
+}
+
+func trimTailAtLine(value string) string {
+	if idx := strings.IndexByte(value, '\n'); idx >= 0 && idx+1 < len(value) {
+		return value[idx+1:]
+	}
+	return value
 }
 
 func FormatError(err error) string {

internal/tools/tools_test.go

@@ -43,6 +43,41 @@ func TestFileTools(t *testing.T) {
 	}
 }
 
+func TestFileSearchSupportsContextAndMaxResults(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "notes.txt")
+	content := strings.Join([]string{"before", "needle one", "middle", "needle two", "after"}, "\n")
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	search := NewFileSearchTool(dir)
+	out, err := search.walkSearch(context.Background(), fileSearchArgs{Query: "needle", ContextLines: 1, MaxResults: 1}, dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"-- ", "before", "needle one", "middle", "stopped after 1 matches"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("search output missing %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "needle two") {
+		t.Fatalf("search should stop after max_results:\n%s", out)
+	}
+}
+
+func TestFormatResultKeepsHeadAndTail(t *testing.T) {
+	input := strings.Join([]string{"head-1", "head-2", strings.Repeat("x", 220), "tail-1", "tail-2"}, "\n")
+	out := FormatResultLimit(input, 220)
+	for _, want := range []string{"head-1", "truncated: showing head and tail", "tail-2"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("formatted output missing %q:\n%s", want, out)
+		}
+	}
+	if len(out) > 220 {
+		t.Fatalf("formatted output len = %d, want <= 220", len(out))
+	}
+}
+
 func TestShellRunTool(t *testing.T) {
 	dir := t.TempDir()
 	if err := os.WriteFile(filepath.Join(dir, "x.txt"), []byte("x"), 0o644); err != nil {
@@ -69,12 +104,12 @@ func TestReadOnlyBuiltinsExposeOpenAICompatibleNamesAndAliases(t *testing.T) {
 		}
 	}
 
-	for _, want := range []string{"file_list", "file_read", "file_search"} {
+	for _, want := range []string{"file_list", "file_read", "file_search", "code_symbols"} {
 		if !slices.Contains(names, want) {
 			t.Fatalf("definitions missing %s: %#v", want, names)
 		}
 	}
-	for _, alias := range []string{"file.list", "file.read", "file.search"} {
+	for _, alias := range []string{"file.list", "file.read", "file.search", "code.symbols"} {
 		if _, ok := registry.Get(alias); !ok {
 			t.Fatalf("alias missing: %s", alias)
 		}
@@ -84,6 +119,34 @@ func TestReadOnlyBuiltinsExposeOpenAICompatibleNamesAndAliases(t *testing.T) {
 	}
 }
 
+func TestCodeSymbolsToolListsGoSymbols(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "sample.go")
+	if err := os.WriteFile(path, []byte(`package sample
+
+import "context"
+
+type Worker struct{}
+type Runner interface{ Run(context.Context) error }
+
+func NewWorker() *Worker { return &Worker{} }
+func (w *Worker) Run(ctx context.Context) error { return nil }
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	tool := NewCodeSymbolsTool(dir)
+	out, err := tool.Execute(context.Background(), json.RawMessage(`{"path":"sample.go"}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"package sample", "imports: context", "type Worker struct", "type Runner interface", "func NewWorker", "method *Worker.Run"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("symbols output missing %q:\n%s", want, out)
+		}
+	}
+}
+
 func TestRegistryCanExposeWebSearch(t *testing.T) {
 	registry := ReadOnlyBuiltins(t.TempDir())
 	registry.Register(NewBuiltinSearchTool(nil))
@@ -132,7 +195,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, 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, web_search, web_fetch"} {
 		if !strings.Contains(withSearch, want) {
 			t.Fatalf("web search instructions missing %q:\n%s", want, withSearch)
 		}