v0.44.0: reasoning-first progress + language matching

- LLM reasoning first sentence becomes live progress indicator header
- System prompt enforces user-facing <20 word reasoning with examples
- Language matching: bot replies in user's language for everything
- render.FirstSentence() extracts first sentence, strips I will/I'll
- Telegram progress bubble: reasoning header + tool previews below
- Fixed memMsgIdx desync after context trimming in loop.go
- Updated CHANGELOG, AGENTS.md, TELEGRAM.md docs

Author: molty3000

AGENTS.md

@@ -12,7 +12,7 @@ It provides context about the project's architecture, conventions, and how to up
 - **Binary:** `odek` — single static binary, ~12 MB, instant startup.
 - **Config:** Five-layer priority: `~/.odek/secrets.env` → `~/.odek/config.json` → `./odek.json` → `ODEK_*` env vars → CLI flags.
 - **Benchmark:** AIEB v2.0 — 80.3% (highest published agent score on the Autonomous Intelligence Engineering Benchmark).
-- **Version:** v0.43.0 — see latest tag at https://github.com/BackendStack21/odek/releases
+- **Version:** v0.44.0 — see latest tag at https://github.com/BackendStack21/odek/releases
 
 ## Source Layout
 

cmd/odek/telegram.go

@@ -173,8 +173,18 @@ func telegramCmd(args []string) error {
 	systemMessage += "- If a tool fails with 'no such file' or returns empty, check pwd first.\n"
 	systemMessage += "- NEVER run 'find /' or recursive searches from root — they hang.\n"
 	systemMessage += "- A single failure means the path or assumption was wrong — fix that,\n"
-	systemMessage += "  don't escalate to a broader search. Narrow, don't widen."
-
+	systemMessage += "  don't escalate to a broader search. Narrow, don't widen.\n"
+	systemMessage += "\n"
+	systemMessage += "## REASONING REMINDER\n"
+	systemMessage += "The first sentence of your reasoning block is the user's live progress indicator. "
+	systemMessage += "Make it brief (<20 words), user-facing, and specific to what you are "
+	systemMessage += "doing right now. Generic self-talk like 'Let me think about this...' "
+	systemMessage += "is useless — users see nothing useful. Start with a real explanation.\n"
+	systemMessage += "\n"
+	systemMessage += "## LANGUAGE REMINDER\n"
+	systemMessage += "Always reply in the exact same language the user writes in. "
+	systemMessage += "Match their language for the answer, the thinking message, "
+	systemMessage += "and the progress indicator. Never switch languages.\n"
 	// Set working directory to the configured repo directory.
 	// This ensures tools like search_files scan the project, not /root.
 	if resolved.GithubRepoDirectory != "" {
@@ -1140,20 +1150,15 @@ func handleChatMessage(
 		}
 	}
 
-	// Collect agent run stats via the iteration callback.
+	// reasoningProgressLine captures the first sentence of LLM reasoning
+	// for use as the progress bubble content in "all"/"new" modes.
+	// Reset at the start of each IsPreTool callback. When empty (no reasoning),
+	// the ToolEventHandler falls back to the old ToolPreview approach.
+	var reasoningProgressLine string
 	var runInfo loop.IterationInfo
 	var allToolsMu sync.Mutex
 	allTools := make(map[string]int)
 
-	// truncateWords limits text to maxWords, appending "…" if trimmed.
-	truncateWords := func(s string, maxWords int) string {
-		words := strings.Fields(s)
-		if len(words) <= maxWords {
-			return s
-		}
-		return strings.Join(words[:maxWords], " ") + "…"
-	}
-
 	// ── Clarify Tool ───────────────────────────────────────────────
 	// Wire the clarify tool with a Telegram-native answer function.
 	// When the agent calls clarify(question), the bot sends an inline
@@ -1275,7 +1280,17 @@ func handleChatMessage(
 					line = telegram.EscapeMarkdown(line)
 					bot.SendMessage(chatID, line,
 						&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
-				} else {
+				} else if toolProgress == "all" || toolProgress == "new" {
+					// Insert reasoning header (first sentence) at top of bubble
+					if reasoningProgressLine != "" {
+						if len(progressLines) == 0 || progressLines[0] != reasoningProgressLine {
+							// Insert reasoning header as first line
+							progressLines = append([]string{reasoningProgressLine}, progressLines...)
+							lastProgressMsg = reasoningProgressLine
+						}
+						reasoningProgressLine = "" // consumed, reset for next call
+					}
+					// Always add tool-specific progress line
 					line := buildProgressLine(name, data)
 					sendProgress(line)
 				}
@@ -1295,13 +1310,21 @@ func handleChatMessage(
 				// bubble already shows the narrated tool call).
 			}
 		},
+		// reasoningProgressLine is set in IsPreTool callback and consumed
+		// by the ToolEventHandler to insert the reasoning header into the
+		// progress bubble, followed by individual tool lines.
 		IterationCallback: func(info loop.IterationInfo) {
-			// Pre-tool callback: show LLM reasoning before tools run.
+			// Pre-tool callback: extract first reasoning sentence for progress.
 			if info.IsPreTool {
+				// Reset from previous iteration
+				reasoningProgressLine = ""
+
 				if info.ReasoningContent != "" {
-					reasoning := truncateWords(info.ReasoningContent, 50)
-					if reasoning != "" {
-						bot.SendMessage(chatID, "💭 "+reasoning,
+					firstSentence := render.FirstSentence(info.ReasoningContent)
+					if firstSentence != "" {
+						reasoningProgressLine = firstSentence
+						// Show as a compact thinking message
+						bot.SendMessage(chatID, "💭 "+firstSentence,
 							&telegram.SendOpts{ReplyToMessageID: messageID})
 					}
 				}

docs/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## v0.44.0 (2026-05-24) — Reasoning-First Progress & Language Matching
+
+### New Features
+- **Reasoning-first progress** — the first sentence of the LLM's internal reasoning (under 20 words, user-facing) now appears at the top of the progress bubble, followed by individual tool previews. The LLM is prompted to make this sentence specific, funny, and engaging:
+  - System prompt includes imperative `REASONING RULE` with ✅/❌ examples and violation consequences
+  - Bottom-of-prompt `REASONING REMINDER` for recency bias
+  - `render.FirstSentence()` extracts the first sentence from reasoning content (handles `. ! ?` boundaries, strips "I will"/"I'll", truncates to 20 words)
+  - Falls back to classic `ToolPreview()` when the model produces no reasoning content
+  - Dedup still works on the reasoning header (`(×N)` for repeated iterations)
+- **Language matching** — the bot always replies in the exact same language the user writes in, enforced at both the top and bottom of the system prompt:
+  - Applies to the final answer, the 💭 thinking message, and the progress indicator
+  - Includes `LANGUAGE RULE` with examples and consequences
+  - Bottom-of-prompt `LANGUAGE REMINDER` for recency bias
+
+### Bug Fixes
+- **`internal/loop/loop.go`** — fixed `memMsgIdx` desync after context trimming: when `trimContext` injects a context-warning system message, the memory message index shifts by 1, causing memory content to be silently dropped. Now detects and adjusts the index
+
+### Documentation
+- **TELEGRAM.md** — updated Tool Progress docs to describe reasoning-first behavior and language matching
+
+### Internal
+- **`render.FirstSentence()`** — new exported function with 6 tests (empty, simple, exclamation, "I will" stripping, no-boundary, long truncation)
+- **`render/render_test.go`** — restored existing test suite (was accidentally overwritten) and appended FirstSentence tests
+- **`cmd/odek/telegram.go`** — removed unused local `truncateWords` closure; replaced with `render.FirstSentence()`
+
 ## v0.43.1 (2026-05-24) — Tool Progress Docs & /mode Command
 
 ### Documentation

docs/TELEGRAM.md

@@ -313,12 +313,14 @@ Tool progress shows what the agent is doing in real time. Controlled by the `too
 
 | Mode | Behavior |
 |------|----------|
-| `all` (default) | Single editable progress bubble with smart previews — e.g. `📝 read_file: "main.go"`. With edit throttling (1.5s), dedup (`×N` counter), and flood-control fallback |
-| `new` | Like `all` but only updates when the tool name changes — skips consecutive same-tool repeats |
+| `all` (default) | Reasoning-first progress: LLM's first reasoning sentence as header, then individual tool previews below. Eg: `"Let me search that file..."` then `📝 read_file: "main.go"`. With edit throttling (1.5s), dedup, and flood-control fallback |
+| `new` | Like `all` but reasoning header only updates on new iteration |
 | `verbose` | Raw tool arguments as separate messages — `📝 `read_file` {"path":"main.go"}` then `📝 `read_file` ✅ (2KB)` on completion |
 | `off` | No per-tool progress messages — just the thinking preamble and final answer |
 
 **Key features:**
+- **Reasoning-first progress** — the first sentence of the LLM's internal reasoning (under 20 words) appears at the top of the progress bubble, followed by individual tool previews. The LLM is prompted to make this sentence user-facing, specific, and engaging
+- **Language matching** — the bot always replies in the same language the user writes in, including the thinking message and progress indicator
 - **Smart previews** — extracts meaningful context: filename for file tools, command for shell, URL for browser, query for memory, filename for transcribe
 - **Edit throttling** — 1.5s minimum between edits prevents Telegram flood control (429 errors)
 - **Tool dedup** — if the same tool runs N times in a row (common with parallel batches), shows `📝 read_file: "main.go" (×5)` instead of 5 identical lines

internal/loop/loop.go

@@ -410,6 +410,19 @@ func (e *Engine) runLoop(ctx context.Context, messages []llm.Message) (string, [
 		// Trim context to stay within model's context window
 		messages = e.trimContext(messages, tools)
 
+		// Resync memMsgIdx after trimContext — when trimContext injects a
+		// context-warning message at index 1, all subsequent messages shift
+		// right by 1, making e.memMsgIdx point to the warning instead of
+		// memory. Detect this by checking if the message at our tracked
+		// position is a trim warning.
+		if e.memMsgIdx > 0 && e.memMsgIdx < len(messages) {
+			if strings.Contains(messages[e.memMsgIdx].Content, "[Context trimmed:") {
+				// Trim warning was injected before our memory message.
+				// The actual memory message is now at memMsgIdx + 1.
+				e.memMsgIdx++
+			}
+		}
+
 		// Load relevant skills based on latest user input (once per message)
 		if e.skillLoader != nil {
 			if userMsg := lastUserMessage(messages); userMsg != "" && userMsg != e.lastSkillMsg {

internal/render/render.go

@@ -269,6 +269,58 @@ func ToolPreview(name, args string) string {
 	return ""
 }
 
+// FirstSentence extracts the first sentence from reasoning/thinking text.
+// Returns a user-facing preview under 20 words. Falls back to truncation
+// if no sentence boundary is found. Returns empty string for empty input.
+// Handles standard punctuation (. ! ?) followed by space or newline, and
+// also handles ellipsis (...) and end-of-input as boundaries.
+func FirstSentence(text string) string {
+	if text == "" {
+		return ""
+	}
+
+	// Clean leading whitespace and reasoning markers
+	text = strings.TrimSpace(text)
+	text = strings.TrimPrefix(text, "I'll")
+	text = strings.TrimPrefix(text, "I will")
+	text = strings.TrimSpace(text)
+
+	// Try standard sentence boundaries
+	for _, sep := range []string{". ", "! ", "? ", ".\n", "!\n", "?\n", "...\n"} {
+		if idx := strings.Index(text, sep); idx > 0 {
+			sentence := strings.TrimSpace(text[:idx+1])
+			if sentence != "" {
+				return truncateWords(sentence, 20)
+			}
+		}
+	}
+
+	// No boundary found — check if the whole thing is short enough
+	if wordCount(text) <= 20 {
+		return text
+	}
+
+	// Truncate to 20 words
+	return truncateWords(text, 20)
+}
+
+// wordCount returns the number of whitespace-delimited words in s.
+func wordCount(s string) int {
+	if strings.TrimSpace(s) == "" {
+		return 0
+	}
+	return len(strings.Fields(s))
+}
+
+// truncateWords limits s to maxWords, appending "…" if trimmed.
+func truncateWords(s string, maxWords int) string {
+	words := strings.Fields(s)
+	if len(words) <= maxWords {
+		return s
+	}
+	return strings.Join(words[:maxWords], " ") + "…"
+}
+
 // extractJSONField extracts the value of a top-level string field from a JSON blob.
 func extractJSONField(jsonStr, field string) string {
 	prefix := `"` + field + `": "`

internal/render/render_test.go

@@ -751,3 +751,54 @@ func TestRenderer_NarratorMessage_NoColor(t *testing.T) {
 		t.Errorf("missing message in no-color output: %q", out)
 	}
 }
+
+func TestFirstSentence_Empty(t *testing.T) {
+	if got := FirstSentence(""); got != "" {
+		t.Errorf("FirstSentence('') = %q, want ''", got)
+	}
+}
+
+func TestFirstSentence_Simple(t *testing.T) {
+	input := "Let me search for that file. I will use grep to find the pattern."
+	got := FirstSentence(input)
+	want := "Let me search for that file."
+	if got != want {
+		t.Errorf("FirstSentence = %q, want %q", got, want)
+	}
+}
+
+func TestFirstSentence_StripsIWill(t *testing.T) {
+	input := "I will check the server logs for errors. Then I can debug further."
+	got := FirstSentence(input)
+	want := "check the server logs for errors."
+	if got != want {
+		t.Errorf("FirstSentence = %q, want %q", got, want)
+	}
+}
+
+func TestFirstSentence_NoBoundary(t *testing.T) {
+	input := "Just a single short phrase"
+	got := FirstSentence(input)
+	want := "Just a single short phrase"
+	if got != want {
+		t.Errorf("FirstSentence = %q, want %q", got, want)
+	}
+}
+
+func TestFirstSentence_TruncateLong(t *testing.T) {
+	input := "I think the best approach would be to first check the configuration file and then run the application to see if it works correctly without any errors."
+	got := FirstSentence(input)
+	words := len(strings.Fields(got))
+	if words > 20 {
+		t.Errorf("FirstSentence = %q has %d words, want ≤20", got, words)
+	}
+}
+
+func TestFirstSentence_WithExclamation(t *testing.T) {
+	input := "Found it! Now let me read the contents."
+	got := FirstSentence(input)
+	want := "Found it!"
+	if got != want {
+		t.Errorf("FirstSentence = %q, want %q", got, want)
+	}
+}

runtime.go

@@ -28,12 +28,51 @@ func BuildRuntimeContext(platform string) string {
 
 	switch platform {
 	case "telegram":
-		ctx += "\n\nYou are on a text messaging communication platform, Telegram. " +
-			"Standard markdown is supported: **bold**, *italic*, ~~strikethrough~~, " +
-			"||spoiler||, `inline code`, ```code blocks```, [links](url), and ## headers. " +
-			"Use the send_message tool to send intermediate messages, files (photo/document/voice), " +
-			"or interactive inline keyboard buttons (buttons parameter with cb: prefix). " +
-			"For final answers, just return the text directly — no need to use send_message."
+			// ═══ REASONING RULE (MANDATORY) — placed FIRST so LLM sees it immediately
+			telegramCtx := "## ⚡ REASONING RULE — FOLLOW THIS EXACTLY\n" +
+				"You MUST start your internal reasoning block with a brief " +
+				"user-facing explanation of what you are about to do.\n" +
+				"- This first sentence becomes the LIVE PROGRESS INDICATOR users see\n" +
+				"- Keep it under 20 words\n" +
+				"- Be specific, funny, and engaging when possible\n" +
+				"- Write it FOR THE USER, not for yourself\n" +
+				"\n" +
+				"✅ GOOD examples:\n" +
+				"  \"Let me dig into that log file for clues...\"\n" +
+				"  \"Alright, pulling the latest changes from git!\"\n" +
+				"  \"One moment — running that test suite to check...\"\n" +
+				"  \"Let me search the codebase for where that error hides...\"\n" +
+				"\n" +
+				"❌ BAD examples (too generic, no user value):\n" +
+				"  \"I'll break this down step by step...\"\n" +
+				"  \"Let me think about this problem...\"\n" +
+				"  \"Okay, let me analyze what's needed here...\"\n" +
+				"  \"First, I need to understand the request...\"\n" +
+				"\n" +
+				"VIOLATION CONSEQUENCE: If you write a generic self-directed first sentence, " +
+				"users see NOTHING useful while you work — they have no clue what is happening. " +
+				"The bot looks broken. Always start with a real explanation.\n\n" +
+				"## 🌐 LANGUAGE RULE — FOLLOW THIS EXACTLY\n" +
+				"You MUST reply in the EXACT SAME LANGUAGE the user writes in.\n" +
+				"- Read the user's language from their message and match it\n" +
+				"- This includes the final answer, the 💭 thinking message, AND the progress indicator\n" +
+				"- NEVER switch languages mid-conversation\n" +
+				"- If unsure, detect the language from the message content\n" +
+				"\n" +
+				"Examples: user writes in Portuguese → reply in Portuguese. " +
+				"User writes in English → reply in English. " +
+				"User writes in Spanish → reply in Spanish.\n" +
+				"\n" +
+				"VIOLATION CONSEQUENCE: Replying in the wrong language confuses the user " +
+				"and makes the bot unusable. Always match the user's language.\n\n" +
+				"You are on a text messaging communication platform, Telegram. " +
+				"Standard markdown is supported: **bold**, *italic*, ~~strikethrough~~, " +
+				"||spoiler||, `inline code`, ```code blocks```, [links](url), and ## headers. " +
+				"Use the send_message tool to send intermediate messages, files (photo/document/voice), " +
+				"or interactive inline keyboard buttons (buttons parameter with cb: prefix). " +
+				"For final answers, just return the text directly — no need to use send_message."
+			// The caller (odek.New) prepends runtimeContext to systemMessage already.
+			ctx += telegramCtx
 
 	case "web":
 		ctx += "\n\nYou are running in a web UI. " +