fix: warn before the tool-call budget runs out, and disclose when it did

The 20-iteration cap is what actually truncated the provisioning session
analysed in 8318f7f, and it explains the ending better than the earlier
read did: the model was mid-thought about running a real end-to-end test
when the budget ran out, and the forced synthesis turned that into a
confident sign-off with a tick beside a step that never executed.

Three things were wrong, none of them the cap value itself.

No warning before the cliff. maybeInjectSoftDeadlineWarning has told the
model about the wall-clock budget since it shipped; the tool-call budget
- the one that actually fires - told it nothing. A turn that plans five
steps and is guillotined after four has no way to prioritise, and the
step it loses is always the last one, which is verification. Adds the
iteration analogue, firing with 30% of the budget left (6 calls of 20):
enough to finish and verify, not enough to start exploring again.

The forced-synthesis nudge optimised for the wrong thing. "Do not
apologize without delivering content" plus "the most complete
deliverable you can" reads as an instruction to sound finished. It now
also requires saying the budget ran out, naming the steps that did not
run, and reporting only what tool results actually showed - being cut
off before a check is not the check passing.

The truncation notice existed only as metadata. iterationCapReached has
exactly one consumer, web/src/components/chat-screen.tsx. WeChat,
Discord, Feishu, LINE and API callers drop it silently, so a truncated
turn arrives on those channels looking like a finished answer with no
indication otherwise. Disclosure that lives in UI chrome does not exist
off that UI; it is now also in the message text for channels that cannot
render the badge, on both the streaming and non-streaming paths (emitted
as a trailing chunk too, since a streaming client renders what it
received, not what was persisted).

The default stays at 20. The session overran it partly on work that no
longer happens - the anti-detect-browser detour, the filesystem-wide
find, a re-read of an already-loaded skill - and provisioning now costs
about five native tool calls instead of a dozen shelled-out CLI
invocations. maxToolIterations remains per-agent configurable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: idoubi

internal/agent/loop.go

@@ -2014,6 +2014,52 @@ func maybeInjectSoftDeadlineWarning(ctx context.Context, turnStart time.Time, me
 	return append(messages, warnMsg), true
 }
 
+// softIterationFraction is the share of the tool-call budget left when
+// the wrap-up warning fires. 0.30 of 20 leaves 6 calls — enough to close
+// out a multi-step task (finish the current step, verify, report) but
+// not enough to start a new line of exploration.
+const softIterationFraction = 0.30
+
+// maybeInjectIterationBudgetWarning is the tool-call analogue of
+// maybeInjectSoftDeadlineWarning.
+//
+// The wall-clock budget has warned the model since it shipped; the
+// iteration budget never did, and it is the one that actually fires. A
+// turn that plans five steps, spends its calls on the first four, and
+// gets guillotined mid-plan produces the worst possible artifact: the
+// forced synthesis reads as a confident completion report, because from
+// the model's point of view it never learned it was about to be cut off.
+// The verification step is what gets dropped — it is always last — so
+// the turn ends by claiming success it never checked.
+//
+// Warning early enough to act is the whole point: this fires with
+// softIterationFraction of the budget left, so the model can spend its
+// remaining calls finishing rather than exploring.
+func maybeInjectIterationBudgetWarning(ctx context.Context, used, max int, messages []provider.Message, alreadyFired bool) ([]provider.Message, bool) {
+	if alreadyFired || max <= 0 {
+		return messages, alreadyFired
+	}
+	remaining := max - used
+	if remaining <= 0 || float64(remaining) > float64(max)*softIterationFraction {
+		return messages, false
+	}
+	emitEvent(ctx, ChatEvent{Type: "status", Data: map[string]any{
+		"phase":                "wrap_up",
+		"remaining_tool_calls": remaining,
+	}})
+	warnMsg := provider.Message{
+		Role: "system",
+		Content: fmt.Sprintf(
+			"Tool budget warning: %d of %d tool calls used — about %d remain before this turn is cut off and "+
+				"a final answer is forced from whatever you have. Stop exploring and start closing out. "+
+				"Spend the remaining calls on finishing the task and on any verification you told the user you would do; "+
+				"verification is the step that gets lost when the budget runs out, and an unverified claim reported as "+
+				"done is worse than an honest 'not yet checked'. If you cannot finish, say plainly which steps did not run.",
+			used, max, remaining),
+	}
+	return append(messages, warnMsg), true
+}
+
 // runToolsWithProgress wraps executeToolsConcurrently with a ticker that
 // emits "tool_progress" events every toolProgressInterval while the
 // call is in flight, so a slow tool (sandbox exec, subagent delegate)
@@ -2269,6 +2315,7 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 	// turn run until it's hard-killed mid-request.
 	turnStart := time.Now()
 	softDeadlineFired := false
+	iterBudgetWarned := false
 
 	// replyParts accumulates every non-empty assistant text segment
 	// emitted across iterations (preamble lines before tool calls + the
@@ -2289,6 +2336,7 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 		)
 
 		messages, softDeadlineFired = maybeInjectSoftDeadlineWarning(ctx, turnStart, messages, softDeadlineFired)
+		messages, iterBudgetWarned = maybeInjectIterationBudgetWarning(ctx, i, a.maxToolIterations, messages, iterBudgetWarned)
 
 		// Hook: BeforeModelCall
 		hcBefore := &HookContext{AgentName: a.name, Point: BeforeModelCall, Messages: messages, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID}
@@ -2655,6 +2703,7 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 		// badge attached.
 		finalContent = fmt.Sprintf("I've reached the maximum number of tool iterations (%d) and couldn't synthesize a final response. The work above represents what I gathered before hitting the limit.", a.maxToolIterations)
 	}
+	finalContent += iterationCapNotice(msg.Channel, a.maxToolIterations)
 	capMeta := mergeMetadata(iterationCapMetadata(a.maxToolIterations), knowledgeMeta)
 	sess.Append(provider.Message{
 		Role:      "assistant",
@@ -3024,10 +3073,12 @@ func (a *Agent) HandleMessageStream(ctx context.Context, msg bus.InboundMessage)
 	streakState := sameToolFailStreakState{}
 	turnStart := time.Now()
 	softDeadlineFired := false
+	iterBudgetWarned := false
 
 	// ReAct loop - use Chat for tool iterations
 	for i := 0; i < a.maxToolIterations; i++ {
 		messages, softDeadlineFired = maybeInjectSoftDeadlineWarning(ctx, turnStart, messages, softDeadlineFired)
+		messages, iterBudgetWarned = maybeInjectIterationBudgetWarning(ctx, i, a.maxToolIterations, messages, iterBudgetWarned)
 
 		hcBefore := &HookContext{AgentName: a.name, Point: BeforeModelCall, Messages: messages, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID}
 		a.hooks.Run(ctx, hcBefore)
@@ -3239,7 +3290,8 @@ func (a *Agent) streamFinalDeliveryAfterCap(ctx context.Context, inboundMsg bus.
 	if err != nil {
 		// Streaming endpoint failed — persist+emit a fallback line
 		// with the badge so the user still gets the signal.
-		fallback := fmt.Sprintf("I've reached the maximum number of tool iterations (%d) and couldn't synthesize a final response. The work above represents what I gathered before hitting the limit.", a.maxToolIterations)
+		fallback := fmt.Sprintf("I've reached the maximum number of tool iterations (%d) and couldn't synthesize a final response. The work above represents what I gathered before hitting the limit.", a.maxToolIterations) +
+			iterationCapNotice(inboundMsg.Channel, a.maxToolIterations)
 		fallbackMsg := provider.Message{Role: "assistant", Content: fallback, Metadata: capMeta, Timestamp: time.Now().UnixMilli()}
 		sess.Append(fallbackMsg)
 		emitEvent(ctx, ChatEvent{Type: "content", Data: map[string]any{"content": fallback, "metadata": capMeta}})
@@ -3287,6 +3339,18 @@ func (a *Agent) streamFinalDeliveryAfterCap(ctx context.Context, inboundMsg bus.
 		if content == "" {
 			content = fmt.Sprintf("I've reached the maximum number of tool iterations (%d) and couldn't synthesize a final response. The work above represents what I gathered before hitting the limit.", a.maxToolIterations)
 		}
+		// Emit the truncation notice as a trailing chunk too, not just in
+		// the persisted message: a streaming consumer renders what it
+		// received, so a notice added only to the stored copy would never
+		// reach the person actually reading the reply.
+		if notice := iterationCapNotice(inboundMsg.Channel, a.maxToolIterations); notice != "" {
+			content += notice
+			select {
+			case outCh <- provider.StreamChunk{Content: notice}:
+			case <-ctx.Done():
+				return
+			}
+		}
 		finalMsg := provider.Message{
 			Role:      "assistant",
 			Content:   content,
@@ -3345,12 +3409,39 @@ func capReachedNudge(maxIterations int) provider.Message {
 	return provider.Message{
 		Role: "system",
 		Content: fmt.Sprintf(
-			"You've used all %d tool-call iterations available for this turn. Tools are now disabled for this final response — do not attempt to call any. Synthesize what you've already gathered into the most complete deliverable you can: if the user asked for a structured artifact (table, list, ICP summary, email drafts, etc.), produce it now from the existing tool results. For any fields you couldn't resolve, mark them as 'unknown' / 'not found' / 'partial' rather than dropping rows or skipping the structure — give the user something usable plus an honest note about what's missing. Do not apologize without delivering content.",
+			"You've used all %d tool-call iterations available for this turn. Tools are now disabled for this final response — do not attempt to call any. "+
+				"Synthesize what you've already gathered into the most complete deliverable you can: if the user asked for a structured artifact (table, list, ICP summary, email drafts, etc.), produce it now from the existing tool results. "+
+				"For any fields you couldn't resolve, mark them as 'unknown' / 'not found' / 'partial' rather than dropping rows or skipping the structure — give the user something usable plus an honest note about what's missing. Do not apologize without delivering content.\n\n"+
+				"Two things you MUST get right, because this turn ended early and the user cannot see that unless you say it:\n"+
+				"- State up front that you ran out of tool budget and the work is incomplete. Name the steps you planned but did not run.\n"+
+				"- Report ONLY what tool results actually showed. Do not mark a step done, tick it off, or call something verified unless a tool result in this conversation confirms it — being cut off before a check is not the same as the check passing. "+
+				"If your last plan step was verification and it never ran, the honest report is 'configured but not verified', never a completion claim.",
 			maxIterations,
 		),
 	}
 }
 
+// iterationCapNotice is the in-band truncation marker for channels that
+// cannot render the iterationCapReached badge.
+//
+// That badge is read by exactly one consumer — the web chat UI. Every
+// other surface (WeChat, Discord, Feishu, LINE, plain API consumers)
+// drops the metadata silently, so a turn that was guillotined mid-plan
+// arrives looking like a finished, confident answer. The disclosure that
+// the work is partial cannot live only in UI chrome; on those channels
+// it has to be in the text or it does not exist.
+//
+// Returns "" for channels that do render the badge, so the web UI
+// doesn't show the same warning twice.
+func iterationCapNotice(channel string, maxIterations int) string {
+	if channel == "web" {
+		return ""
+	}
+	return fmt.Sprintf(
+		"\n\n---\n⚠️ This turn hit its %d tool-call limit and was cut short — the answer above is built from partial results, and any step described as done was not necessarily verified. Reply to continue.",
+		maxIterations)
+}
+
 // iterationCapMetadata is the assistant-side metadata stamped on the
 // forced final-delivery message so the UI can badge the bubble. Kept
 // as a constructor so the key name stays canonical across the streaming

internal/agent/loop_stall_test.go

@@ -230,3 +230,98 @@ func TestUpdateSameToolFailStreak(t *testing.T) {
 	})
 }
 
+
+// The tool-call budget is the limit that actually fires in practice, yet
+// it warned nobody until now — only the wall-clock budget did. A turn
+// that plans five steps and gets cut off after four ends by reporting
+// the fifth as done, because the model never learned it was running out.
+func TestMaybeInjectIterationBudgetWarning_FiresOnceNearTheCap(t *testing.T) {
+	ctx := context.Background()
+	base := []provider.Message{{Role: "user", Content: "go"}}
+
+	// 13 of 20 used: 7 left, above the 30% threshold — stay quiet.
+	got, fired := maybeInjectIterationBudgetWarning(ctx, 13, 20, base, false)
+	if fired || len(got) != len(base) {
+		t.Fatalf("must not fire while budget is comfortable (fired=%v, msgs=%d)", fired, len(got))
+	}
+
+	// 14 of 20: 6 left, exactly at 30% — warn.
+	got, fired = maybeInjectIterationBudgetWarning(ctx, 14, 20, base, false)
+	if !fired {
+		t.Fatal("expected the warning to fire with 30% of the budget left")
+	}
+	if len(got) != len(base)+1 {
+		t.Fatalf("expected one appended system message, got %d", len(got))
+	}
+	warn := got[len(got)-1]
+	if warn.Role != "system" {
+		t.Errorf("warning should be a system message, got role %q", warn.Role)
+	}
+	for _, want := range []string{"Tool budget warning", "verification"} {
+		if !strings.Contains(warn.Content, want) {
+			t.Errorf("warning missing %q: %s", want, warn.Content)
+		}
+	}
+
+	// Already fired — never append twice in one turn.
+	got2, fired2 := maybeInjectIterationBudgetWarning(ctx, 18, 20, got, true)
+	if !fired2 || len(got2) != len(got) {
+		t.Errorf("warning must fire at most once per turn")
+	}
+}
+
+// A budget already spent has nothing to warn about — the cap nudge takes
+// over at that point.
+func TestMaybeInjectIterationBudgetWarning_NoBudgetNoFire(t *testing.T) {
+	ctx := context.Background()
+	base := []provider.Message{{Role: "user", Content: "go"}}
+	if _, fired := maybeInjectIterationBudgetWarning(ctx, 20, 20, base, false); fired {
+		t.Error("must not fire when the budget is already exhausted")
+	}
+	if _, fired := maybeInjectIterationBudgetWarning(ctx, 0, 0, base, false); fired {
+		t.Error("must not fire when no cap is configured")
+	}
+}
+
+// The cap-reached banner is rendered by exactly one consumer — the web
+// chat UI. On every other channel the metadata is dropped, so without an
+// in-band notice a guillotined turn arrives looking like a finished,
+// confident answer.
+func TestIterationCapNoticeReachesNonWebChannels(t *testing.T) {
+	if notice := iterationCapNotice("web", 20); notice != "" {
+		t.Errorf("web renders its own badge; text notice would duplicate it: %q", notice)
+	}
+	for _, ch := range []string{"wechat", "discord", "feishu", "line", "api", ""} {
+		notice := iterationCapNotice(ch, 20)
+		if notice == "" {
+			t.Errorf("channel %q silently drops the cap metadata and needs an in-band notice", ch)
+			continue
+		}
+		if !strings.Contains(notice, "20") {
+			t.Errorf("notice for %q should name the limit: %q", ch, notice)
+		}
+		if !strings.Contains(notice, "not necessarily verified") {
+			t.Errorf("notice for %q should undercut completion claims: %q", ch, notice)
+		}
+	}
+}
+
+// The forced-synthesis nudge used to push purely toward "deliver
+// content", which is how a truncated turn produced a confident
+// completion report with a tick next to a step that never ran.
+func TestCapReachedNudgeDemandsHonestyAboutTruncation(t *testing.T) {
+	msg := capReachedNudge(20)
+	if msg.Role != "system" {
+		t.Fatalf("nudge role = %q", msg.Role)
+	}
+	for _, want := range []string{
+		"ran out of tool budget",
+		"did not run",
+		"unless a tool result",
+		"configured but not verified",
+	} {
+		if !strings.Contains(msg.Content, want) {
+			t.Errorf("nudge should require honesty about %q:\n%s", want, msg.Content)
+		}
+	}
+}