fix(foreground-fallback): make replay notification self-explanatory to the model

[mhenke]

Fixes #1072

What problem are you solving?

The foreground-fallback hook replays the last user message with a fallback model and appends an internal synthetic part whose text is the terse string Foreground fallback replay. (plus the <!-- SLIM_INTERNAL_INITIATOR --> marker). This part is sent to the model (intended — synthetic parts are hidden from the UI but reach the model), but the text is ambiguous: the model does not recognize it as an internal system instruction, treats it as a leak, and does not know how to handle it.

What does this change?

Replaces the terse Foreground fallback replay. text with a self-explanatory <system-reminder> block that tells the model the previous request failed, is being retried with a fallback model, to continue processing the user's original request, and not to respond to the reminder.

Why this approach?

The orchestrator-wake hook already uses the <system-reminder> wrapper pattern for internal initiators (ORCHESTRATOR_WAKE_TEXT / ORCHESTRATOR_STOPPED_JOB_WAKE_TEXT), which the model understands as an internal notification. The foreground-fallback replay is the same kind of system-level notification, so matching that pattern is the consistent choice. No other alternatives were considered — this is the established pattern for internal initiators in this repo.

Related work

• I checked open AND closed PRs/issues for duplicates
• Related: [Bug]: Foreground fallback replay injects ambiguous text that confuses the model #1072 (this fix); fix(foreground-fallback): protect managed child sessions and skip replay after streamed output #1011, fix(foreground-fallback): retry same-model on streaming 5xx errors for agents without chains #951, fix(foreground-fallback): replay v2 user messages and detect quota-threshold errors #976 (other foreground-fallback PRs, different concerns)

AI assistance

• Model / harness: OpenCode (deepseek-ai/deepseek-v4-flash-0731). The code edit was made directly by the orchestrator; no subagents were used for the edit. Root-cause investigation used @explorer subagents to verify SDK serialization preserves synthetic and to inspect TUI rendering.
• Human reviewed the full diff? [x] (sign-off given before submission)

Checklist

• bun run typecheck and bun test pass; bun run check:ci has pre-existing unrelated failures in other files (tracked by fix: resolve pre-existing check:ci failures (tui.ts + format) #1067) — this change's file passes Biome cleanly
• Docs (README.md, docs/) updated if behavior/commands changed — no doc change needed; this is an internal prompt text change, not user-facing behavior/config
• One logical change per PR
• PR targets the master branch

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Greptile Summary

Updates the foreground-fallback replay notification so fallback models receive a clear internal instruction instead of an ambiguous terse marker.

• Wraps the replay explanation in the established <system-reminder> format.
• Directs the fallback model to continue the original request without responding to the reminder.

Confidence Score: 5/5

The PR appears safe to merge, with no actionable regression identified in the changed replay notification.

The new static reminder accurately describes every foreground-fallback trigger, follows the repository’s existing internal-reminder format, and preserves the original replay payload ordering and request shape.

Important Files Changed

Filename	Overview
src/hooks/foreground-fallback/index.ts	Replaces the internal fallback replay label with a static, self-explanatory system reminder while preserving replay ordering and request structure.

_{Reviews (1): Last reviewed commit: "fix(foreground-fallback): make replay no..." | Re-trigger Greptile}