feat: add 'enhance' interaction mode — narrated tool messages, persist after response

Author: molty3000

cmd/odek/telegram.go

@@ -1009,18 +1009,23 @@ func handleChatMessage(
 		}
 	}()
 
-	// ── Engaging Mode: Immediate Progress ──────────────────────────
+	// ── Progress Mode Setup ───────────────────────────────────────
 	// Send an instant "working on it" message so the user sees feedback
-	// within milliseconds, not seconds. This message gets updated with
-	// narrator-style progress on each tool call, then deleted when the
-	// final answer arrives.
+	// within milliseconds, not seconds.
+	//
+	//   engaging: updated with narrated tool descriptions (edits), then
+	//             deleted when the final answer arrives.
+	//   enhance:  kept as a per-iteration header; narrated tool messages
+	//             are appended below it as new messages (no edits).
+	//   verbose:  no progress message — uses raw tool traces instead.
 	var narrator *narrate.Narrator
-	isEngaging := resolved.InteractionMode != "verbose"
-	if isEngaging {
+	isEngaging := resolved.InteractionMode == "engaging"
+	isEnhance := resolved.InteractionMode == "enhance"
+	if isEngaging || isEnhance {
 		narrator = narrate.New(true)
 	}
 	var progressMsgID int
-	if isEngaging {
+	if isEngaging || isEnhance {
 		msg, err := bot.SendMessage(chatID, "🤔 Looking into that...",
 			&telegram.SendOpts{ReplyToMessageID: messageID})
 		if err == nil {
@@ -1029,9 +1034,10 @@ func handleChatMessage(
 	}
 	defer func() {
 		// Clean up the progress message when the task finishes.
-		// The final answer replaces it entirely — this avoids cluttering
-		// the chat with a stale "thinking" message.
-		if progressMsgID != 0 {
+		// In engaging mode, deletes the stale "thinking" message.
+		// In enhance mode, preserves it as a per-iteration header
+		// with the narrated tool messages below it.
+		if progressMsgID != 0 && isEngaging {
 			bot.DeleteMessage(chatID, progressMsgID)
 		}
 	}()
@@ -1149,9 +1155,28 @@ func handleChatMessage(
 		Tools:           agentTools,
 		Renderer:        rend,
 		ToolEventHandler: func(event string, name string, data string) {
+			// Enhance mode: send new messages with narrated descriptions.
+			// Each tool call gets its own message (no edits, no cleanup).
+			if isEnhance {
+				switch event {
+				case "tool_call":
+					if narrator != nil {
+						if msg := narrator.ToolCallMessage(name, data); msg != "" {
+							escapedMsg := telegram.EscapeMarkdown(msg)
+							bot.SendMessage(chatID, escapedMsg,
+								&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
+						}
+					}
+				case "tool_result":
+					// silent in enhance mode -- the narrated tool_call
+					// message already describes what's happening.
+				}
+				return
+			}
+
 			// Engaging mode: update the progress message with narrated tool
 			// descriptions instead of raw traces.
-			if resolved.InteractionMode != "verbose" {
+			if isEngaging {
 				if progressMsgID != 0 && event == "tool_call" && narrator != nil {
 					if msg := narrator.ToolCallMessage(name, data); msg != "" {
 						bot.EditMessageText(chatID, progressMsgID, msg, nil)

cmd/odek/telegram_test.go

@@ -564,6 +564,107 @@ func TestModeCommand(t *testing.T) {
 	}
 }
 
+// TestEnhanceMode_SendsNarratedMessages tests that enhance mode sends
+// new narrated messages per tool_call (no edits, no cleanup, silent tool_result).
+func TestEnhanceMode_SendsNarratedMessages(t *testing.T) {
+	bot := newMockBot()
+
+	chatID := int64(123)
+	messageID := 1
+	isEnhance := true
+
+	// Simulate the narrator for enhance mode
+	type narrateMsg struct{}
+	var progressMsgID int
+	if isEnhance {
+		msg, _ := bot.SendMessage(chatID, "🤔 Looking into that...",
+			&telegram.SendOpts{ReplyToMessageID: messageID})
+		if msg != nil {
+			progressMsgID = msg.ID
+		}
+	}
+
+	// Simulate enhance-mode tool handler
+	toolHandler := func(event string, name string, data string) {
+		if !isEnhance {
+			return
+		}
+		switch event {
+		case "tool_call":
+			msg := narratorToolCallMessage(name, data)
+			if msg != "" {
+				bot.SendMessage(chatID, msg,
+					&telegram.SendOpts{ParseMode: telegram.ParseModeMarkdownV2})
+			}
+		case "tool_result":
+			// silent in enhance mode
+		}
+	}
+
+	// Fire events: one iteration with reasoning + 2 tool calls
+	toolHandler("tool_call", "read_file", `{"path":"/etc/hostname"}`)
+	toolHandler("tool_result", "read_file", `{"content":"my-host"}`)
+	toolHandler("tool_call", "shell", `{"command":"go test ./..."}`)
+	toolHandler("tool_result", "shell", `{"output":"PASS","exit_code":0}`)
+
+	calls := bot.recorded()
+	t.Logf("Enhance mode sequence (%d calls):", len(calls))
+	for i, c := range calls {
+		t.Logf("  %d. %s %q (msgID=%d)", i+1, c.Method, truncateStr(c.Text, 60), c.MsgID)
+	}
+
+	// Expected: 3 sendMessages (thinking node + 2 narrated tool_call)
+	// No edits, no deletes
+	if len(calls) != 3 {
+		t.Fatalf("expected 3 calls (thinking node + 2 narrated), got %d", len(calls))
+	}
+
+	// Call 1: thinking node
+	if calls[0].Method != "sendMessage" || !strings.Contains(calls[0].Text, "🤔") {
+		t.Errorf("call 1: expected sendMessage with thinking node, got %s %q", calls[0].Method, calls[0].Text)
+	}
+
+	// Call 2: narrated read_file
+	if calls[1].Method != "sendMessage" || !strings.Contains(calls[1].Text, "📖") {
+		t.Errorf("call 2: expected sendMessage with narrated read_file, got %s %q", calls[1].Method, calls[1].Text)
+	}
+
+	// Call 3: narrated shell
+	if calls[2].Method != "sendMessage" || !strings.Contains(calls[2].Text, "⚙️") {
+		t.Errorf("call 3: expected sendMessage with narrated shell, got %s %q", calls[2].Method, calls[2].Text)
+	}
+
+	// No editMessageText
+	for _, c := range calls {
+		if c.Method == "editMessageText" {
+			t.Errorf("unexpected editMessageText in enhance mode: %q", c.Text)
+		}
+	}
+
+	// No deleteMessage
+	for _, c := range calls {
+		if c.Method == "deleteMessage" {
+			t.Errorf("unexpected deleteMessage in enhance mode (msgID=%d)", c.MsgID)
+		}
+	}
+
+	// Verify progressMsgID is NOT deleted (it was stored but defer cleanup
+	// skipped it because isEngaging=false)
+	_ = progressMsgID
+}
+
+// narratorToolCallMessage replicates the narrator's ToolCallMessage for tests.
+func narratorToolCallMessage(name, args string) string {
+	switch name {
+	case "read_file":
+		return "📖 Reading `hostname`..."
+	case "shell":
+		return "⚙️ Running `go test ./...`..."
+	default:
+		return "🔧 Working on `" + name + "`..."
+	}
+}
+
 // truncateStr truncates a string for display in test logs.
 func truncateStr(s string, n int) string {
 	if len(s) <= n {

internal/config/loader.go

@@ -70,7 +70,8 @@ type CLIFlags struct {
 	GithubRepoUrl string
 
 	// InteractionMode controls how tool-call progress is surfaced.
-	// "engaging" (default) = LLM-narrated, emoji-rich explanations.
+	// "engaging" (default) = emoji-rich narration, progress message edited.
+	// "enhance" = per-tool narrated messages appended, progress header kept.
 	// "verbose" = raw tool names, args, and results.
 	InteractionMode string
 }
@@ -166,7 +167,8 @@ type FileConfig struct {
 	GithubRepoUrl string `json:"github_repo_url,omitempty"`
 
 	// InteractionMode controls how the agent communicates tool/progress updates.
-	// "engaging" (default) = LLM-narrated, emoji-rich explanations.
+	// "engaging" (default) = emoji-rich narration, progress message edited.
+	// "enhance" = per-tool narrated messages, progress header kept.
 	// "verbose" = raw tool names, args, and results.
 	InteractionMode string `json:"interaction_mode,omitempty"`
 }
@@ -261,7 +263,7 @@ type ResolvedConfig struct {
 	GithubRepoUrl string
 
 	// InteractionMode is the resolved interaction style.
-	// "engaging" (default) or "verbose".
+	// "engaging" (default), "enhance", or "verbose".
 	InteractionMode string
 }
 

internal/telegram/commands.go

@@ -137,6 +137,7 @@ func modeHandler(args string) (string, error) {
 	return "⚙️ *Agent Modes*\n\n" +
 		"Modes are set at startup via `odek.json` or CLI flags:\n" +
 		"• `interaction_mode: engaging` — emoji-rich narration (default)\n" +
+		"• `interaction_mode: enhance` — narrated tool summaries (persist)\n" +
 		"• `interaction_mode: verbose` — raw tool call output\n" +
 		"• `sandbox: true` — run in Docker isolation\n" +
 		"• `skills.verbose: true` — show skill learning details\n\n" +

odek.go

@@ -114,7 +114,7 @@ type Config struct {
 	// after each tool invocation. Used by the WebUI for live streaming.
 	ToolEventHandler func(event string, name string, data string)
 
-	// InteractionMode controls tool-call rendering: "engaging" (default) or "verbose".
+	// InteractionMode controls tool-call rendering: "engaging" (default), "enhance", or "verbose".
 	InteractionMode string
 
 	// IterationCallback, if set, is invoked after each iteration of the
@@ -566,9 +566,9 @@ func New(cfg Config) (*Agent, error) {
 		engine.SetIterationCallback(cfg.IterationCallback)
 	}
 
-	// Wire narrator for engaging interaction mode (default).
+	// Wire narrator for engaging/enhance interaction modes.
 	// In verbose mode, narrator stays nil → existing renderer behavior.
-	if cfg.InteractionMode == "" || cfg.InteractionMode == "engaging" {
+	if cfg.InteractionMode == "" || cfg.InteractionMode == "engaging" || cfg.InteractionMode == "enhance" {
 		engine.SetNarrator(narrate.New(true))
 	}