feat: file attachments via --ctx flag and @ref resolution in CLI

Adds two ways to inject file content into agent prompts:

1. --ctx / -c flag:
   odek run --ctx main.go,lib.go 'analyze these files'
   odek run -c data.csv 'what does this contain?'

2. @ reference resolution (inline, works like Web UI):
   odek run '@src/main.go what does this do?'
   odek continue '@session-id continue from here'

Both work in odek run, odek continue, and the REPL.

--ctx errors on missing files (fail-fast). @refs that can't be
resolved are left as-is in the prompt (graceful fallback).

7 new tests covering: no-refs passthrough, @ref resolution,
--ctx injection, both combined, missing ctx file error, flag parsing.

Author: jkyberneees

cmd/odek/main.go

@@ -169,6 +169,7 @@ type runFlags struct {
 	Session  *bool // nil = not set; true = save session after run
 	Learn    *bool // nil = not set; true = enable skills learning mode
 	Task     string
+	Ctx      []string // --ctx files to attach
 
 	// Sandbox-specific CLI flags
 	SandboxImage    string // Docker image (e.g. "node:20-alpine")
@@ -242,6 +243,9 @@ func parseRunFlags(args []string) (runFlags, error) {
 		case "--sandbox-user":
 			f.SandboxUser = args[i+1]
 			i += 2
+		case "--ctx", "-c":
+			f.Ctx = strings.Split(args[i+1], ",")
+			i += 2
 		default:
 			// Not a flag — treat remaining as the task
 			goto done
@@ -687,6 +691,14 @@ func run(args []string) error {
 		SandboxUser:     f.SandboxUser,
 	})
 
+	// Resolve @references and --ctx file attachments in the task
+	cwd, _ := os.Getwd()
+	enriched, err := enrichTask(f.Task, f.Ctx, cwd)
+	if err != nil {
+		return err
+	}
+	f.Task = enriched
+
 	// Determine system message: CLI/project/env override, or default
 	systemMessage := resolved.System
 	if systemMessage == "" {
@@ -1362,6 +1374,13 @@ func continueCmd(args []string) error {
 	}
 	task := strings.Join(args[i:], " ")
 
+	// Resolve @references in the continue task
+	cwd, _ := os.Getwd()
+	enriched, err := enrichTask(task, nil, cwd)
+	if err == nil {
+		task = enriched
+	}
+
 	store, err := session.NewStore()
 	if err != nil {
 		return fmt.Errorf("session store: %w", err)

cmd/odek/refs.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/BackendStack21/kode/internal/resource"
+)
+
+// enrichTask resolves @references in the task prompt and prepends
+// --ctx file attachments. Returns the enriched prompt ready for
+// the LLM, or an error if any --ctx file can't be read.
+//
+// @refs that fail to resolve are left as-is in the text.
+//
+// Examples:
+//
+//	odek run "@main.go what does this do?"
+//	  → resolves @main.go to file content, replaces inline
+//
+//	odek run --ctx main.go "analyze this"
+//	  → prepends file content as context block
+//
+//	odek run --ctx lib.go,util.go "@main.go compare these"
+//	  → both ctx files + @ref resolution
+func enrichTask(task string, ctxFiles []string, cwd string) (string, error) {
+	reg := resource.NewRegistry(resource.NewFileResolver(cwd))
+
+	// Step 1: Resolve @ references in the task
+	enriched := task
+	refs := resource.ParseRefs(task)
+	if len(refs) > 0 {
+		resolved := make(map[string]string)
+		for _, ref := range refs {
+			content, err := reg.Load(context.Background(), ref.Raw)
+			if err != nil {
+				// Leave unresolved refs as-is
+				continue
+			}
+			resolved[ref.Raw] = content
+		}
+		enriched = resource.ReplaceRefs(task, resolved)
+	}
+
+	// Step 2: Add --ctx files as preamble
+	if len(ctxFiles) > 0 {
+		var blocks []string
+		for _, f := range ctxFiles {
+			f = strings.TrimSpace(f)
+			if f == "" {
+				continue
+			}
+			content, err := reg.Load(context.Background(), "@"+f)
+			if err != nil {
+				return "", fmt.Errorf("ctx file %q: %w", f, err)
+			}
+			blocks = append(blocks, fmt.Sprintf("--- %s ---\n%s\n--- end %s ---", f, content, f))
+		}
+		if len(blocks) > 0 {
+			// Log attached files to stderr
+			fmt.Fprintf(os.Stderr, "odek: attached %d file(s)\n", len(blocks))
+			enriched = strings.Join(blocks, "\n\n") + "\n\n" + enriched
+		}
+	}
+
+	return enriched, nil
+}

cmd/odek/refs_test.go

@@ -0,0 +1,120 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestEnrichTask_NoRefsOrCtx(t *testing.T) {
+	result, err := enrichTask("hello world", nil, "/tmp")
+	if err != nil {
+		t.Fatalf("enrichTask error: %v", err)
+	}
+	if result != "hello world" {
+		t.Errorf("expected unchanged task, got %q", result)
+	}
+}
+
+func TestEnrichTask_WithAtRef(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "hello.txt")
+	os.WriteFile(src, []byte("Hello, World!"), 0644)
+
+	result, err := enrichTask("@hello.txt what does this say?", nil, dir)
+	if err != nil {
+		t.Fatalf("enrichTask error: %v", err)
+	}
+
+	if !strings.Contains(result, "Hello, World!") {
+		t.Errorf("expected file content in result, got %q", result)
+	}
+	if !strings.Contains(result, "@hello.txt") {
+		t.Errorf("expected @reference in result header, got %q", result)
+	}
+}
+
+func TestEnrichTask_WithCtxFile(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "data.txt")
+	os.WriteFile(src, []byte("file content"), 0644)
+
+	result, err := enrichTask("analyze this", []string{"data.txt"}, dir)
+	if err != nil {
+		t.Fatalf("enrichTask error: %v", err)
+	}
+
+	if !strings.Contains(result, "file content") {
+		t.Errorf("expected ctx file content in result, got %q", result)
+	}
+	if !strings.HasPrefix(result, "--- data.txt ---") {
+		t.Errorf("expected ctx block header at start, got %q", result)
+	}
+	if !strings.Contains(result, "analyze this") {
+		t.Errorf("expected task at end, got %q", result)
+	}
+}
+
+func TestEnrichTask_CtxFileNotFound(t *testing.T) {
+	_, err := enrichTask("analyze this", []string{"nonexistent.txt"}, t.TempDir())
+	if err == nil {
+		t.Fatal("expected error for nonexistent ctx file")
+	}
+}
+
+func TestEnrichTask_WithBothCtxAndAtRef(t *testing.T) {
+	dir := t.TempDir()
+	os.WriteFile(filepath.Join(dir, "main.txt"), []byte("main content"), 0644)
+	os.WriteFile(filepath.Join(dir, "lib.txt"), []byte("lib content"), 0644)
+
+	result, err := enrichTask("@lib.txt compare with ctx", []string{"main.txt"}, dir)
+	if err != nil {
+		t.Fatalf("enrichTask error: %v", err)
+	}
+
+	if !strings.Contains(result, "main content") {
+		t.Errorf("expected ctx file content: %q", result)
+	}
+	if !strings.Contains(result, "lib content") {
+		t.Errorf("expected @ref file content: %q", result)
+	}
+}
+
+func TestParseRunFlags_CtxFlag(t *testing.T) {
+	f, err := parseRunFlags([]string{
+		"--ctx", "main.go,lib.go",
+		"analyze these files",
+	})
+	if err != nil {
+		t.Fatalf("parseRunFlags error: %v", err)
+	}
+	if len(f.Ctx) != 2 {
+		t.Fatalf("expected 2 ctx files, got %d: %v", len(f.Ctx), f.Ctx)
+	}
+	if f.Ctx[0] != "main.go" {
+		t.Errorf("Ctx[0] = %q, want %q", f.Ctx[0], "main.go")
+	}
+	if f.Ctx[1] != "lib.go" {
+		t.Errorf("Ctx[1] = %q, want %q", f.Ctx[1], "lib.go")
+	}
+	if f.Task != "analyze these files" {
+		t.Errorf("Task = %q, want %q", f.Task, "analyze these files")
+	}
+}
+
+func TestParseRunFlags_CtxShortFlag(t *testing.T) {
+	f, err := parseRunFlags([]string{
+		"-c", "data.csv",
+		"analyze",
+	})
+	if err != nil {
+		t.Fatalf("parseRunFlags error: %v", err)
+	}
+	if len(f.Ctx) != 1 || f.Ctx[0] != "data.csv" {
+		t.Errorf("Ctx = %v, want [data.csv]", f.Ctx)
+	}
+	if f.Task != "analyze" {
+		t.Errorf("Task = %q, want %q", f.Task, "analyze")
+	}
+}

cmd/odek/repl.go

@@ -205,6 +205,12 @@ func replCmd(args []string) error {
 			continue
 		}
 
+		// Resolve @references in REPL input
+		cwd, _ := os.Getwd()
+		if enriched, err := enrichTask(input, nil, cwd); err == nil {
+			input = enriched
+		}
+
 		// Build message history: session messages + new user input
 		messages := sess.GetMessages()
 		origLen := len(messages)