fix(agent): strip leaked harmony reasoning-channel from visible content

[laurinaitis]

Summary

Some models use OpenAI's harmony response format, which separates private reasoning (an analysis/commentary channel) from the user-facing answer (a final channel) with control tokens:

<|start|>assistant<|channel|>analysis<|message|>…reasoning…<|end|>
<|start|>assistant<|channel|>final<|message|>…answer…<|return|>

When such a model is served via Ollama and Ollama's native thinking-parse misses, that reasoning leaks into the visible message content — the user sees the raw chain-of-thought plus stray <channel|> markers before the real answer. This adds grammar-faithful, false-positive-guarded stripping of that leak, centralised in one module and applied at every sync-coupled site that emits or persists assistant content.

This is defense-in-depth for a parse miss, and it's the same class of fix the agent already does for leaked harmony tool-call serialization in agent/codex_responses_adapter.py::_TOOL_CALL_LEAK_PATTERN (which strips <|channel|>commentary to=functions.… out of visible content). Leaked harmony structure in content is treated here, consistently, as an in-agent bug to clean — not something to leave to the transport. It also plays the same role strip_think_blocks already plays for MiniMax (<mm:think>, #8878/#9568) and the tool-call XML port (#67318), and is the kind of stripper invited in #45211.

Symptom

A real captured leak (assistant message, thinking on):

thought
The user wants me to… My persona should…        ← chain-of-thought
…
<channel|>The computer, eh? The glowing window to every…   ← the real answer

The whole plan ships to the user, followed by a bare <channel|> separator, then the actual reply. Two shapes occur in the wild: the degraded shape above (leading control token eaten by Ollama's partial parse, leaving a bare channel-name word) and the canonical full-token form.

The fix

New module agent/harmony_scrub.py:

• strip_harmony_leak(text) — for a complete message. Returns text unchanged unless it begins with harmony structure. Canonical → keep everything after the last final-channel marker; degraded → strip the leading reasoning up to and including the first lone <channel|> after the head (following word kept verbatim). An analysis-only leak (a channel head with no final marker and no later separator) is discarded rather than returned with its delimiters merely peeled off — otherwise the chain-of-thought would ship and persist de-tokenised into history where it can never be re-detected.
• HarmonyStreamGate — a watch/suppress/done state machine for the streaming path; holds back a leaked prefix delta-by-delta (even when control tokens are split across deltas) and releases only the answer tail. It re-arms on flush, so an intra-turn retry stream (thinking-only prefill, empty-response retry — the same case as a569226) is still guarded.

Applied at every sync-coupled site that emits or persists assistant content (whole bug class, not just the reported surface):

Layer	Where
Persisted / post-hoc	agent_runtime_helpers.py::strip_think_blocks (and run_agent._strip_think_blocks, a forwarder)
Live stream	agent/think_scrubber.py::StreamingThinkScrubber
CLI display	cli.py::_strip_reasoning_tags
Iteration-limit summaries	chat_completion_helpers.py::handle_max_iterations (both summary sites — previously hand-rolled a <think>-only, case-sensitive strip and appended straight to messages, bypassing the storage-boundary scrub)
Auxiliary / vision fallback	auxiliary_client.py::extract_content_or_reasoning (guarded <think> but not harmony)

False-positive safety

The harmony grammar is matched case-sensitively against the literal lowercase channel names (analysis/commentary/final) — the tokens are emitted verbatim lowercase, so exact case is positive evidence from the grammar, and it means an ordinary capitalised heading is never mistaken for a channel head. Both entry points also only engage when text begins with harmony structure, and a bare channel-name word must stand alone (followed by a newline or a harmony token — not a colon). Verified untouched (complete-string and streamed):

• "Analysis of Q2 revenue: we grew 12%." (word followed by prose)
• "Analysis\nModels emit <|channel|>final<|message|> before the answer." (capitalised heading that even quotes the final marker)
• "Commentary\nRunning the tests now; the <|channel|> token is next." (capitalised heading + quoted token)
• "Analysis:\nThe format uses a <|channel|> token…" (heading and a quoted token)
• normal replies stream byte-for-byte unchanged

The global stray-token strip runs only on a confirmed leak's recovered tail, never on arbitrary content.

Not a collision with display.show_commentary

This scrubs a degenerate serialization of harmony control tokens leaking into content; it does not touch the Codex commentary channel feature. Codex commentary is a structured phase="commentary" message item surfaced through the Codex runtime (agent/codex_runtime.py, gated by the display.show_commentary config toggle), never a raw token stream — no harmony control tokens or bare channel-name head reach this module on that path, so show_commentary: true output is unaffected.

Tests

tests/agent/test_harmony_scrub.py (new) + the existing tests/agent/test_think_scrubber.py — 72 pass, including upstream's flush boundary tests from a569226. Covers both leak shapes, multi-block/commentary, the over-strip regressions (an answer starting "Final…"; a canonical leak; a heading-plus-quoted-token), the analysis-only discard (complete + streaming), the capitalised-heading false-positive class (complete + streaming), the streaming gate re-arm after flush, per-hook wiring for strip_think_blocks and cli._strip_reasoning_tags, streaming with tokens split across deltas, <think>-tag regression (unchanged), and a battery of benign inputs that must be untouched.

Rebased onto current main.

Relates to #56213, #45211.