talon-agent 1.9.2 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/prompts/telegram.md

@@ -2,15 +2,33 @@
 
 In groups, you'll see messages prefixed with [Name]: — use their name naturally.
 
-### CRITICAL: Message delivery
+### Response flow — IMPORTANT
 
-ALL messages to the user MUST be sent using the `send` tool. Your plain text output is **private** — the user never sees it, only you. Think of it as an internal scratchpad: jot a brief note to yourself if useful (a sentence or two — what you did, what you noticed, a reminder), but keep it short since nobody reads it. The only way to reach the user is the `send` tool.
+Your output stream (this prose right here) is **private scratchpad**. The user never sees it. The ONLY ways for content to reach the user are:
 
-### The `send` tool
+- **`end_turn(text=...)`** — the canonical way to deliver your final reply. Closes the turn. Optional `reply_to` for threaded replies, optional `buttons` for inline keyboards.
+- **`end_turn()`** with no args — explicit silent close. Use this when you've done what you needed to (e.g. reacted with an emoji, ran a tool that didn't need a reply) and want to make it clear that the silence is intentional.
+- **`send(...)`** — for mid-turn rich content (photos, polls, voice, stickers, scheduled messages, multi-message responses, multi-target). Does NOT close the turn — typically followed by `end_turn(...)` or `end_turn()`.
+- **`react(message_id, emoji)`** — emoji reaction on a message. Often the right response to acknowledge without replying. Pair with `end_turn()` to close cleanly.
 
-One tool for everything. Set `type` to choose what to send:
+**There is no fallback.** Prose written without an `end_turn` / `send` call is scratchpad — dropped. If you write a thoughtful response in your output stream and forget to wrap it in `end_turn(text=...)`, the user sees nothing. Get into the habit of ending every turn with one of the closing options above.
 
-- `send(type="text", text="Hello!")` — send a message
+Doing nothing — no tool call at all — is also a valid silent close (the model genuinely had nothing to do), but `end_turn()` makes the intent explicit and is preferred when the silence is deliberate.
+
+**Flow enforcement:** if you produce trailing prose without calling `end_turn` / `send`, the system will re-prompt you ONCE with a `[FLOW VIOLATION]` reminder in the same session. You'll see your broken turn in history and get a fresh turn to redo it correctly. Burns 2x the tokens for that exchange, so just call `end_turn` the first time.
+
+### When to use `send` vs `end_turn`
+
+- **`end_turn`** = the final reply that ends your turn. Plain text + optional reply_to + optional buttons. The closer.
+- **`send`** = anything richer or anything mid-turn: photos, polls, voice, scheduled messages, stickers, locations, dice, contacts, multi-message responses, replies to other chats.
+
+For a plain text final reply, prefer `end_turn(text=...)` over `send(type="text", text=...)`. They reach the same delivery path, but the name makes the intent unambiguous.
+
+### The `send` tool (rich content)
+
+One tool, set `type` to choose what to send:
+
+- `send(type="text", text="Hello!")` — plain text (use end_turn instead for final reply)
 - `send(type="text", text="Hey", reply_to=12345)` — reply to a specific message
 - `send(type="text", text="Pick", buttons=[[{"text":"A","callback_data":"a"}]])` — with buttons
 - `send(type="text", text="Reminder", delay_seconds=60)` — schedule for later
@@ -54,7 +72,7 @@ The user's message ID is in the prompt as [msg_id:N]. Use with `reply_to` and `r
 You don't HAVE to respond to every message. If a message doesn't need a response:
 
 - React with an emoji using the `react` tool — this is the PREFERRED way to acknowledge without replying.
-- Or simply don't call `send` and skip it entirely.
+- Or call `end_turn()` with no args to end the turn silently.
 - In groups, prefer reactions over replies for simple acknowledgements.
 
 ### Reactions

package/src/__tests__/end-turn.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Unit tests for the `end_turn` tool and the cross-tool dedup helpers used to
+ * suppress duplicate deliveries when the model calls both `end_turn` and
+ * `send(type="text")` with similar content in the same turn.
+ *
+ * Covers:
+ *   - normalizeForDedupe / isDuplicateOfDelivered (dedup math)
+ *   - end_turn tool definition (schema, dispatch, silent path)
+ *   - StreamState carries lastTrailingText and deliveredTextNorms
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import {
+  normalizeForDedupe,
+  isDuplicateOfDelivered,
+  createStreamState,
+} from "../backend/claude-sdk/stream.js";
+import { messagingTools } from "../core/tools/messaging.js";
+import { isTurnTerminator, ALL_TOOLS } from "../core/tools/index.js";
+
+describe("normalizeForDedupe", () => {
+  it("trims, lowercases, and collapses whitespace", () => {
+    expect(normalizeForDedupe("  Hello   World  ")).toBe("hello world");
+    expect(normalizeForDedupe("HELLO\n\tWORLD")).toBe("hello world");
+  });
+
+  it("strips emoji so prose-with-emoji matches messaging-tool-text", () => {
+    expect(normalizeForDedupe("Got it 👍")).toBe("got it");
+    expect(normalizeForDedupe("Done ✅ and dusted")).toBe("done and dusted");
+  });
+
+  it("returns empty string for whitespace-only input", () => {
+    expect(normalizeForDedupe("   \n\t  ")).toBe("");
+  });
+});
+
+describe("isDuplicateOfDelivered", () => {
+  it("returns false when nothing has been delivered yet", () => {
+    expect(isDuplicateOfDelivered("hello there", [])).toBe(false);
+  });
+
+  it("returns false for very short candidates (below dedup threshold)", () => {
+    // Below MIN_DEDUP_LENGTH (10) — short replies like "ok" / "sure" should
+    // never be deduped, even if they happened to coincide with a longer
+    // delivered text containing them.
+    expect(isDuplicateOfDelivered("ok", ["ok thanks pal"])).toBe(false);
+  });
+
+  it("matches when normalized candidate is a substring of delivered", () => {
+    const delivered = [normalizeForDedupe("Got it sur, pushing now")];
+    expect(isDuplicateOfDelivered("Got it sur, pushing now", delivered)).toBe(
+      true,
+    );
+  });
+
+  it("matches when normalized delivered is a substring of candidate", () => {
+    // Model called end_turn(text="Pushing now") then wrote prose
+    // "I'm pushing now and back in a sec." — fuzzy match catches this.
+    const delivered = [normalizeForDedupe("Pushing now")];
+    expect(
+      isDuplicateOfDelivered("I'm pushing now and back in a sec.", delivered),
+    ).toBe(true);
+  });
+
+  it("does not match unrelated content", () => {
+    const delivered = [normalizeForDedupe("PR #106 merged")];
+    expect(
+      isDuplicateOfDelivered("Got it, I'll look at the docker logs", delivered),
+    ).toBe(false);
+  });
+
+  it("ignores emoji differences when comparing", () => {
+    // Model wrote "Done 🎉" as prose, also called end_turn(text="Done")
+    const delivered = [normalizeForDedupe("Done")];
+    expect(isDuplicateOfDelivered("Done 🎉", delivered)).toBe(false);
+    // Above is false because "done" (3 chars) < MIN_DEDUP_LENGTH (10).
+    // For a longer match:
+    const longDelivered = [normalizeForDedupe("All set, pushing now")];
+    expect(
+      isDuplicateOfDelivered("All set, pushing now 🚀", longDelivered),
+    ).toBe(true);
+  });
+});
+
+describe("createStreamState", () => {
+  it("initializes lastTrailingText and deliveredTextNorms", () => {
+    const state = createStreamState();
+    expect(state.lastTrailingText).toBe("");
+    expect(state.deliveredTextNorms).toEqual([]);
+  });
+
+  it("initializes turnTerminated to false", () => {
+    const state = createStreamState();
+    expect(state.turnTerminated).toBe(false);
+  });
+});
+
+describe("turn-terminator declaration", () => {
+  it("end_turn is declared with endsTurn: true", () => {
+    const endTurn = messagingTools.find((t) => t.name === "end_turn");
+    expect(endTurn?.endsTurn).toBe(true);
+  });
+
+  it("send is NOT declared as a turn terminator", () => {
+    // `send` is for mid-turn rich content (photos, polls, scheduled messages,
+    // etc.) — calling it does NOT mean the model is done. Only end_turn
+    // declares the turn finished.
+    const send = messagingTools.find((t) => t.name === "send");
+    expect(send?.endsTurn).toBeFalsy();
+  });
+
+  it("isTurnTerminator returns true for end_turn", () => {
+    expect(isTurnTerminator("end_turn")).toBe(true);
+  });
+
+  it("isTurnTerminator returns false for non-terminator tools", () => {
+    expect(isTurnTerminator("send")).toBe(false);
+    expect(isTurnTerminator("react")).toBe(false);
+    expect(isTurnTerminator("fetch_url")).toBe(false);
+    expect(isTurnTerminator("nonexistent_tool")).toBe(false);
+  });
+
+  it("only one turn terminator currently exists (end_turn)", () => {
+    // If a future change adds a second terminator, this test should fail
+    // and the author should document why a new terminator is necessary.
+    const terminators = ALL_TOOLS.filter((t) => t.endsTurn).map((t) => t.name);
+    expect(terminators).toEqual(["end_turn"]);
+  });
+});
+
+describe("end_turn tool definition", () => {
+  const endTurn = messagingTools.find((t) => t.name === "end_turn");
+
+  it("is registered in messagingTools", () => {
+    expect(endTurn).toBeDefined();
+    expect(endTurn?.tag).toBe("messaging");
+    expect(endTurn?.frontends).toEqual(["telegram", "teams"]);
+  });
+
+  it("has text, reply_to, and buttons schema fields", () => {
+    expect(endTurn?.schema).toBeDefined();
+    expect(endTurn?.schema.text).toBeDefined();
+    expect(endTurn?.schema.reply_to).toBeDefined();
+    expect(endTurn?.schema.buttons).toBeDefined();
+  });
+
+  it("dispatches plain text via send_message bridge", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    await endTurn!.execute({ text: "Hello sur" }, bridge);
+    expect(bridge).toHaveBeenCalledWith("send_message", {
+      text: "Hello sur",
+      reply_to_message_id: undefined,
+    });
+  });
+
+  it("dispatches text + reply_to via send_message bridge", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    await endTurn!.execute({ text: "Yep", reply_to: 12345 }, bridge);
+    expect(bridge).toHaveBeenCalledWith("send_message", {
+      text: "Yep",
+      reply_to_message_id: 12345,
+    });
+  });
+
+  it("dispatches text + buttons via send_message_with_buttons bridge", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    const buttons = [[{ text: "Click", callback_data: "x" }]];
+    await endTurn!.execute({ text: "Pick", buttons }, bridge);
+    expect(bridge).toHaveBeenCalledWith("send_message_with_buttons", {
+      text: "Pick",
+      rows: buttons,
+      reply_to_message_id: undefined,
+    });
+  });
+
+  it("ends silently with no bridge call when text is omitted", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    const result = await endTurn!.execute({}, bridge);
+    expect(bridge).not.toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, silent: true });
+  });
+
+  it("ends silently with no bridge call when text is whitespace-only", async () => {
+    const bridge = vi.fn(async () => ({ ok: true }));
+    const result = await endTurn!.execute({ text: "   \n\t  " }, bridge);
+    expect(bridge).not.toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, silent: true });
+  });
+});

package/src/__tests__/handlers.test.ts

@@ -2676,13 +2676,19 @@ describe("processAndReply — group message without senderId", () => {
   }, 3000);
 });
 
-describe("processAndReply — suppressed fallback text logged (L572 TRUE branch)", () => {
-  it("logs when bridgeMessageCount=0 and result.text is non-empty", async () => {
+describe("processAndReply — fallback text no longer suppressed", () => {
+  // Pre-end_turn behavior: when bridgeMessageCount=0 and result.text was
+  // non-empty, the frontend logged "Suppressed fallback text" and dropped
+  // the content (the scratchpad bug). The handler now fires onTextBlock
+  // with trailing text instead, so:
+  //   - the "Suppressed fallback" log is gone entirely
+  //   - the delivery path is exercised by createStreamCallbacks tests above
+  it("does NOT log a 'Suppressed fallback' warning anymore", async () => {
     const { log } = await import("../util/log.js");
     (log as ReturnType<typeof vi.fn>).mockClear();
 
     executeMock.mockResolvedValueOnce({
-      text: "internal reasoning only",
+      text: "trailing prose that used to be suppressed",
       durationMs: 10,
       inputTokens: 1,
       outputTokens: 1,
@@ -2694,7 +2700,7 @@ describe("processAndReply — suppressed fallback text logged (L572 TRUE branch)
     const ctx = {
       chat: { id: 99600, type: "private" },
       message: {
-        text: "test suppressed fallback",
+        text: "test fallback delivery",
         message_id: 1600,
         reply_to_message: null,
       },
@@ -2709,7 +2715,7 @@ describe("processAndReply — suppressed fallback text logged (L572 TRUE branch)
     const suppressedLog = logCalls.find((c: unknown[]) =>
       String(c[1]).includes("Suppressed fallback"),
     );
-    expect(suppressedLog).toBeDefined();
+    expect(suppressedLog).toBeUndefined();
   }, 3000);
 });
 

package/src/backend/claude-sdk/handler.ts

@@ -24,6 +24,7 @@ import { log, logError, logWarn } from "../../util/log.js";
 import { traceMessage } from "../../util/trace.js";
 import { incrementCounter, recordHistogram } from "../../util/metrics.js";
 import { formatFullDatetime } from "../../util/time.js";
+import { isTurnTerminator } from "../../core/tools/index.js";
 
 import type { Query } from "@anthropic-ai/claude-agent-sdk";
 import type { QueryParams, QueryResult } from "../../core/types.js";
@@ -38,6 +39,8 @@ import {
   processStreamDelta,
   processAssistantMessage,
   processResultMessage,
+  normalizeForDedupe,
+  isDuplicateOfDelivered,
 } from "./stream.js";
 
 // ── Active query store ──────────────────────────────────────────────────────
@@ -92,6 +95,30 @@ export async function handleMessage(
   activeQueries.set(chatId, qi);
   const state = createStreamState();
 
+  // Capture text args from delivery tools (`end_turn`, `send(type="text")`)
+  // so the end-of-turn trailing-text fallback can dedupe against content
+  // already delivered. Without this, a model that writes prose AND calls a
+  // delivery tool with similar text would surface twice in the chat.
+  const captureDeliveredText = (
+    toolName: string,
+    input: Record<string, unknown>,
+  ): void => {
+    let deliveredText: string | undefined;
+    if (toolName === "end_turn" && typeof input.text === "string") {
+      deliveredText = input.text;
+    } else if (
+      toolName === "send" &&
+      input.type === "text" &&
+      typeof input.text === "string"
+    ) {
+      deliveredText = input.text;
+    }
+    if (deliveredText) {
+      const norm = normalizeForDedupe(deliveredText);
+      if (norm) state.deliveredTextNorms.push(norm);
+    }
+  };
+
   try {
     for await (const message of qi) {
       // Session ID capture
@@ -110,9 +137,18 @@ export async function handleMessage(
       if (isAssistant(message)) {
         const result = processAssistantMessage(message, state);
 
-        // Notify tool usage
+        // Track the trailing text from this assistant message. Multiple
+        // assistant messages can fire per turn (one per tool-use round-trip);
+        // only the LAST one's trailingText is the user-facing final reply.
+        state.lastTrailingText = result.trailingText;
+
+        // Notify tool usage + capture delivery-tool text for end-of-turn dedup
         for (const tool of result.tools) {
           incrementCounter(`tool_calls.${tool.name}`);
+          captureDeliveredText(tool.name, tool.input);
+          if (isTurnTerminator(tool.name)) {
+            state.turnTerminated = true;
+          }
           if (onToolUse) {
             try {
               onToolUse(tool.name, tool.input);
@@ -132,6 +168,26 @@ export async function handleMessage(
             }
           }
         }
+
+        // Turn-terminator tool was called (e.g. `end_turn`). Abort the SDK
+        // loop cleanly so the model can't keep producing trailing scratchpad
+        // after declaring "I'm done". Without this, the model is free to
+        // think more, call more tools, or write more prose — and any prose
+        // afterwards trips the flow-violation re-prompt path. Calling
+        // qi.interrupt() lets the SDK yield its terminal result and exit
+        // the for-await loop on the next iteration.
+        if (state.turnTerminated) {
+          try {
+            await qi.interrupt();
+          } catch (err) {
+            // Non-fatal: interrupt failures shouldn't break the turn,
+            // they just mean the natural end-of-stream path will run.
+            logWarn(
+              "agent",
+              `[${chatId}] qi.interrupt() after turn terminator failed: ${(err as Error)?.message ?? err}`,
+            );
+          }
+        }
         continue;
       }
 
@@ -224,6 +280,55 @@ export async function handleMessage(
     }
   }
 
+  // ── Trailing-prose contract + flow-violation retry ──────────────────────
+  // The output stream is private scratchpad by design. Final replies must go
+  // through `end_turn` (canonical) or `send` (mid-turn rich content). When a
+  // turn ends with no tool call AND no trailing prose, that's valid silent
+  // close (model only reacted, or had nothing to do). When the model wrote
+  // prose but didn't route it through a delivery tool, that's a flow
+  // violation — the prose is private scratchpad, dropped from the user's
+  // view. To prevent these from going unnoticed, we re-prompt the model
+  // ONCE with a synthetic system message in the same session: it sees its
+  // broken turn in history + a reminder of the contract, and gets a fresh
+  // turn to deliver via end_turn. If it violates again on the retry, we
+  // give up loudly and accept the silent drop.
+  //
+  // Exception: if a turn-terminator tool (e.g. end_turn) was called, the
+  // model explicitly declared "I'm done" — respect it. Any trailing prose
+  // that slipped in earlier in the same assistant message gets logged but
+  // does NOT re-prompt (would loop endlessly with a model that pairs prose
+  // with end_turn).
+  const trailing = state.lastTrailingText.trim();
+  const flowViolation =
+    trailing.length > 0 &&
+    !state.turnTerminated &&
+    !isDuplicateOfDelivered(trailing, state.deliveredTextNorms);
+
+  if (flowViolation) {
+    incrementCounter("scratchpad.trailing_text_dropped");
+    log(
+      "agent",
+      `[${chatId}] flow violation: trailing prose (${trailing.length} chars) without end_turn/send. ${
+        _retried
+          ? "Already retried — accepting silent drop."
+          : "Re-prompting with reminder."
+      }`,
+    );
+
+    if (!_retried) {
+      incrementCounter("scratchpad.flow_violation_retried");
+      const reminder =
+        "[FLOW VIOLATION] You produced text content but didn't call `end_turn` or `send`. " +
+        "Pure prose in your output stream is private scratchpad — it's dropped, the user " +
+        "never sees it. Please retry with the proper flow: " +
+        "`end_turn(text=...)` to deliver a final reply, " +
+        "`end_turn()` (no args) to close silently, or " +
+        "`send(...)` for mid-turn rich content (photos, polls, etc.). " +
+        "Respond now using the correct tool call.";
+      return handleMessage({ ...params, text: reminder }, true);
+    }
+  }
+
   // ── Build result ──────────────────────────────────────────────────────────
 
   state.allResponseText += state.currentBlockText;

package/src/backend/claude-sdk/stream.ts

@@ -34,6 +34,33 @@ export type StreamState = {
   sdkCacheRead: number;
   sdkCacheWrite: number;
   lastStreamUpdate: number;
+  /**
+   * Trailing text from the most recent assistant message — text after all
+   * tool_use blocks (or the full text when no tools were called). NOT
+   * delivered to the user (the output stream is private scratchpad by
+   * contract). Tracked so the handler can log a diagnostic when the model
+   * wrote prose without routing it through `end_turn` / `send` — surfaces
+   * missed end_turn calls in metrics rather than silently dropping content.
+   */
+  lastTrailingText: string;
+  /**
+   * Normalized text args observed on `end_turn` / `send(type="text")` tool
+   * calls during this turn. Cross-tool dedup: if both fire with similar
+   * content (e.g. model calls both with the same text mid-turn), the
+   * second one can be matched against this list to avoid the user seeing
+   * the same message twice. Also used to silence the trailing-prose
+   * diagnostic when the prose just duplicates what was already delivered.
+   */
+  deliveredTextNorms: string[];
+  /**
+   * Set when a tool with `endsTurn: true` (e.g. `end_turn`) was observed
+   * in this turn. Once true, the handler invokes `qi.interrupt()` to abort
+   * the SDK loop cleanly — the model can't produce more trailing scratchpad
+   * after this point. Also gates the flow-violation re-prompt: if the model
+   * explicitly ended its turn, we don't re-prompt for trailing prose that
+   * may have appeared in the same assistant message before the terminator.
+   */
+  turnTerminated: boolean;
 };
 
 export function createStreamState(): StreamState {
@@ -50,6 +77,9 @@ export function createStreamState(): StreamState {
     sdkCacheRead: 0,
     sdkCacheWrite: 0,
     lastStreamUpdate: 0,
+    lastTrailingText: "",
+    deliveredTextNorms: [],
+    turnTerminated: false,
   };
 }
 
@@ -224,3 +254,40 @@ export function processResultMessage(
     state.currentBlockText = msg.result;
   }
 }
+
+// ── Trailing-text fallback dedup ────────────────────────────────────────────
+
+/**
+ * Normalize text for fuzzy comparison — trim, lowercase, collapse whitespace,
+ * strip emoji. Used to detect whether trailing prose duplicates content
+ * already delivered via `end_turn` / `send(type="text")`.
+ */
+export function normalizeForDedupe(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/\p{Emoji_Presentation}|\p{Extended_Pictographic}/gu, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const MIN_DEDUP_LENGTH = 10;
+
+/**
+ * Returns true if `candidate` is substantively the same as any text in
+ * `deliveredNorms`. "Substantively" = one is a substring of the other after
+ * normalization; both must be at least MIN_DEDUP_LENGTH chars to avoid
+ * dropping short legitimate replies.
+ */
+export function isDuplicateOfDelivered(
+  candidate: string,
+  deliveredNorms: string[],
+): boolean {
+  if (deliveredNorms.length === 0) return false;
+  const norm = normalizeForDedupe(candidate);
+  if (norm.length < MIN_DEDUP_LENGTH) return false;
+  return deliveredNorms.some(
+    (d) =>
+      d.length >= MIN_DEDUP_LENGTH && (norm.includes(d) || d.includes(norm)),
+  );
+}

package/src/core/tools/index.ts

@@ -30,6 +30,24 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...adminTools,
 ];
 
+/**
+ * Names of tools that explicitly terminate the model's turn.
+ *
+ * Backend handlers consume this set to abort their stream loop after
+ * observing one of these tools — without it, the model can keep producing
+ * trailing scratchpad prose after declaring "I'm done", which trips the
+ * flow-violation re-prompt path. Declaration is on the tool definition
+ * (`endsTurn: true`); detection is shared; abort is backend-specific.
+ */
+const TURN_TERMINATOR_NAMES: ReadonlySet<string> = new Set(
+  ALL_TOOLS.filter((t) => t.endsTurn).map((t) => t.name),
+);
+
+/** Whether a tool call by this name should terminate the model's turn. */
+export function isTurnTerminator(toolName: string): boolean {
+  return TURN_TERMINATOR_NAMES.has(toolName);
+}
+
 /** Filter options for composing a tool set. */
 export interface ComposeOptions {
   /** Include only tools available on this frontend. */

package/src/core/tools/messaging.ts

@@ -1,5 +1,6 @@
 /**
- * Messaging tools — send, react, edit, delete, forward, pin/unpin, stop poll.
+ * Messaging tools — send, end_turn, react, edit, delete, forward, pin/unpin,
+ * stop poll.
  */
 
 import { z } from "zod";
@@ -7,6 +8,83 @@ import type { ToolDefinition } from "./types.js";
 import { idSchema } from "./schemas.js";
 
 export const messagingTools: ToolDefinition[] = [
+  // ── end_turn — explicit final-reply delivery ──────────────────────────
+  // Schema-typed alternative to relying on a trailing-text fallback. The
+  // model is taught that this is the canonical way to deliver its final
+  // reply. Functionally a thin wrapper over send(type="text") + reply_to +
+  // buttons; the value is in the EXPLICIT semantic ("this ends my turn")
+  // and that the model sees a single tool whose purpose is unambiguous.
+  //
+  // The output stream is private scratchpad by contract. If the model
+  // writes trailing prose without calling end_turn or send, the handler
+  // re-prompts ONCE in the same session with a flow-violation reminder
+  // so the model can retry properly. Persistent violation after retry
+  // results in silent drop + `scratchpad.trailing_text_dropped` counter.
+  // `end_turn` is the documented happy path.
+  {
+    name: "end_turn",
+    description: `End your current turn and deliver your final reply to the user. This is the canonical way to respond.
+
+Call this AT MOST ONCE per turn — it should be the last tool you call. Behaves like send(type="text") with reply_to and buttons support, but the name makes the intent explicit: this is the message that ends the turn.
+
+Examples:
+  end_turn(text="Got it sur") — plain reply
+  end_turn(text="On it", reply_to=12345) — reply to a specific message ID
+  end_turn(text="Pick one", buttons=[[{"text":"A","callback_data":"a"}]]) — with buttons
+  end_turn() — silent end (no message; useful when you already replied via earlier send/react calls)
+
+Notes:
+- For richer message types (photos, polls, voice, scheduled messages, multi-target), use the send tool — those don't fit "final reply" semantics.
+- The output stream is private scratchpad. If you write prose without calling end_turn or send, the handler re-prompts you ONCE with a flow-violation reminder so you can retry properly. Persistent violation drops the prose silently. end_turn is the documented happy path.`,
+    schema: {
+      text: z
+        .string()
+        .optional()
+        .describe(
+          "Final reply text. Supports Markdown. Omit to end the turn silently (no message sent).",
+        ),
+      reply_to: idSchema
+        .optional()
+        .describe("Message ID to reply to (typically the user's [msg_id:N])"),
+      buttons: z
+        .array(
+          z.array(
+            z.object({
+              text: z.string(),
+              url: z.string().optional(),
+              callback_data: z.string().optional(),
+            }),
+          ),
+        )
+        .optional()
+        .describe("Inline keyboard button rows"),
+    },
+    execute: async (params, bridge) => {
+      // Telegram path: routes to the same bridge actions as send(type="text")
+      // so bridgeMessageCount, dedup, and audit logging all stay consistent.
+      if (typeof params.text !== "string" || params.text.trim() === "") {
+        // Silent end — no bridge call. The handler still sees the tool was
+        // invoked (via deliveredTextNorms staying empty), and trailing-text
+        // fallback won't fire because there was no trailing prose.
+        return { ok: true, silent: true };
+      }
+      if (params.buttons) {
+        return bridge("send_message_with_buttons", {
+          text: params.text,
+          rows: params.buttons,
+          reply_to_message_id: params.reply_to,
+        });
+      }
+      return bridge("send_message", {
+        text: params.text,
+        reply_to_message_id: params.reply_to,
+      });
+    },
+    frontends: ["telegram", "teams"],
+    tag: "messaging",
+    endsTurn: true,
+  },
+
   // ── Telegram unified send ─────────────────────────────────────────────
   {
     name: "send",

package/src/core/tools/types.ts

@@ -58,4 +58,18 @@ export interface ToolDefinition {
 
   /** Grouping tag. */
   readonly tag: ToolTag;
+
+  /**
+   * This tool explicitly ends the model's turn. Backend handlers observe
+   * this flag to abort their stream loop cleanly after the tool's bridge
+   * call completes — without it, the model is free to keep producing
+   * trailing prose into private scratchpad after declaring "I'm done",
+   * which then trips the flow-violation re-prompt path. With this flag,
+   * an end_turn call genuinely ends the turn.
+   *
+   * Backend abort mechanism is backend-specific (Claude SDK uses
+   * Query.interrupt(); other backends manage their own loop) — this flag
+   * is the shared declarative signal, not the implementation.
+   */
+  readonly endsTurn?: boolean;
 }

package/src/frontend/teams/index.ts

@@ -14,7 +14,7 @@ import type { Gateway } from "../../core/gateway.js";
 import { log, logError } from "../../util/log.js";
 import { deriveNumericChatId } from "../../util/chat-id.js";
 import { resolveModel } from "../../core/models.js";
-import { createTeamsActionHandler } from "./actions.js";
+import { createTeamsActionHandler, postToTeams } from "./actions.js";
 import { splitTeamsMessage, buildAdaptiveCard } from "./formatting.js";
 import {
   initGraphClient,
@@ -356,18 +356,28 @@ export function createTeamsFrontend(
                   `  tool: ${toolName}${detail ? ` — ${String(detail).slice(0, 100)}` : ""}`,
                 );
               },
-            })
-              .then(async (result) => {
-                // Only deliver messages sent via the send_message tool.
-                // Do NOT send fallback text — if the model chose not to use send_message,
-                // it's either choosing not to respond or outputting internal reasoning
-                // that shouldn't be shown to users.
-                if (result.bridgeMessageCount === 0 && result.text?.trim()) {
-                  log(
+              // Deliver assistant text (progress text before tool calls AND
+              // the end-of-turn trailing-text fallback) to the Teams chat.
+              // Without this, prose-only assistant turns would be silently
+              // dropped — same scratchpad bug Telegram hit.
+              onTextBlock: async (blockText) => {
+                if (!blockText.trim()) return;
+                try {
+                  await postToTeams(webhookUrl, blockText);
+                  gateway.incrementMessages(numericChatId);
+                } catch (err) {
+                  logError(
                     "teams",
-                    `Suppressed fallback text (${result.text.length} chars) — no send_message tool used`,
+                    `onTextBlock postToTeams failed: ${err instanceof Error ? err.message : err}`,
                   );
                 }
+              },
+            })
+              .then(async (_result) => {
+                // No fallback delivery — turns without end_turn / send_message
+                // are intentional silent ends. Trailing prose without a tool
+                // call is scratchpad and dropped; the SDK handler emits a
+                // `scratchpad.trailing_text_dropped` metric on those.
               })
               .catch((err) => {
                 logError(

package/src/frontend/telegram/handlers.ts

@@ -781,16 +781,10 @@ async function processAndReply(params: ProcessAndReplyParams): Promise<void> {
       },
     });
 
-    if (
-      result.bridgeMessageCount === 0 &&
-      !stream.sentTextBlock &&
-      result.text?.trim()
-    ) {
-      log(
-        "bot",
-        `Suppressed fallback text (${result.text.length} chars) — no send tool used`,
-      );
-    }
+    // No fallback delivery — turns that don't call `end_turn` / `send` are
+    // intentional silent ends. Trailing prose written without a tool call is
+    // scratchpad and dropped (the SDK handler logs a `scratchpad.trailing_
+    // text_dropped` metric so missed end_turn calls show up in counters).
   } finally {
     clearTimeout(streamTimer);
   }