# NousResearch/hermes-agent · Codex commentary-phase text leaking as visible output

## Open now

- Nothing open on GitHub.

A bug where Codex's pre-tool-call commentary or preamble text is incorrectly routed as visible assistant content to chat gateways instead of being kept in an internal reasoning channel. Multiple fixes and reports address this same routing issue.

## TL;DR

- 5 member(s): 0 open issue(s), 2 closed issue(s), 0 open PR(s), 1 merged PR(s), 2 PR(s) closed without merging.
- A fix was merged to main in PR #58868. Verify it addresses your case.
- **Recommended:** read PR #58868 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-58868`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_SPANNING`): every member is connected by structural evidence: shared changed files, or a closing/superseded reference.
- Pairwise link density `0.44`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Closed / duplicate issues

- #24933: \[Bug\]: Codex Responses commentary-phase tool planning leaks as visible Telegram text
- #41293: GPT-5.5 (openai-codex): pre-tool-call preamble text leaks as visible assistant content to chat gateways since v0.16.0

## Prior & competing PRs

- **#58868: fix(codex): route commentary-phase text to the reasoning channel (salvage #58696 + #41343)**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `agent/codex_responses_adapter.py`, `agent/codex_runtime.py`, `scripts/release.py`, `tests/run_agent/test_run_agent_codex_responses.py`
  - fix hunks:
  - `agent/codex_responses_adapter.py`

    ```diff
    @@ -1166,15 +1166,28 @@ def _normalize_codex_response(
             if item_type == "message":
                 item_phase = getattr(item, "phase", None)
                 normalized_phase = None
    +            is_commentary_phase = False
                 if isinstance(item_phase, str):
                     normalized_phase = item_phase.strip().lower()
                     if normalized_phase in {"commentary", "analysis"}:
                         saw_commentary_phase = True
    +                    is_commentary_phase = True
                     elif normalized_phase in {"final_answer", "final"}:
                         saw_final_answer_phase = True
                 message_text = _extract_responses_message_text(item)
                 if message_text:
    -                content_parts.append(message_text)
    +                # Responses ``commentary``/``analysis`` phase text is mid-turn
    +                # preamble/progress narration, never the turn's final answer
    +                # (Codex CLI excludes it from last-message extraction; issues
    +                # #24933 / #41293).  Keep it out of assistant content so it
    +                # can't be concatenated into — or leak as — the final response,
    +                # but surface it through the reasoning channel so the CLI/
    +                # gateway display it like thinking text.  The exact message
    +                # item is still preserved below for replay/cache continuity.
    +                if is_commentary_phase:
    +                    reasoning_parts.append(message_text)
    +                else:
    +                    content_parts.append(message_text)
                     raw_message_item: Dict[str, Any] = {
                         "type": "message",
                         "role": "assistant",
    ```

    ```diff
    @@ -1269,7 +1282,11 @@ def _normalize_codex_response(
                 ))
     
         final_text = "\n".join([p for p in content_parts if p]).strip()
    -    if not final_text and hasattr(response, "output_text"):
    +    if (
    +        not final_text
    +        and hasattr(response, "output_text")
    +        and not (saw_commentary_phase and not saw_final_answer_phase)
    +    ):
             out_text = getattr(response, "output_text", "")
             if isinstance(out_text, str):
                 final_text = out_text.strip()
    ```
  - `agent/codex_runtime.py`

    ```diff
    @@ -500,6 +500,14 @@ def _event_field(event: Any, name: str, default: Any = None) -> Any:
         return value if value is not None else default
     
     
    +def _item_field(item: Any, name: str, default: Any = None) -> Any:
    +    """Field access for nested Response items (attr-style SDK object or dict)."""
    +    value = getattr(item, name, None)
    +    if value is None and isinstance(item, dict):
    +        value = item.get(name, default)
    +    return value if value is not None else default
    +
    +
     def _raise_stream_error(event: Any) -> None:
         """Raise a ``_StreamErrorEvent`` from a ``type=error`` SSE frame.
     
    ```

    ```diff
    @@ -562,6 +570,7 @@ def _consume_codex_event_stream(
         collected_text_deltas: List[str] = []
         has_tool_calls = False
         first_delta_fired = False
    +    active_message_phase: str | None = None
         terminal_status: str = "completed"
         terminal_usage: Any = None
         terminal_response_id: str = None
    ```

    ```diff
    @@ -595,9 +604,35 @@ def _consume_codex_event_stream(
             if event_type == "error":
                 _raise_stream_error(event)
     
    +        # Track the phase of the active streamed message item.  Codex/Harmony
    +        # ``commentary``/``analysis`` text is mid-turn preamble/progress
    +        # narration, never the final answer.  We still collect completed output
    +        # items for replay, but route those deltas to the reasoning callback so
    +        # they display like thinking text instead of assistant content.
    +        if event_type == "response.output_item.added":
    +            item = _event_field(event, "item")
    +            item_type = _item_field(item, "type", "")
    +            if item_type == "message":
    +                phase = _item_field(item, "phase", None)
    +                active_message_phase = phase.strip().lower() if isinstance(phase, str) else None
    +            else:
    +                active_message_phase = None
    +            if "function_call" in str(item_type):
    +                has_tool_calls = True
    +            continue
    +
             if "output_text.delta" in event_type or event_type == "response.output_text.delta":
                 delta_text = _event_field(event, "delta", "")
    -            if delta_text:
    +            is_commentary_delta = active_message_phase in {"commentary", "analysis"}
    +            if delta_text and is_commentary_delta:
    +                # Commentary streams through the reasoning channel, not the
    +                # visible answer stream (and stays out of output_text).
    +                if on_reasoning_delta is not None:
    +                    try:
    +                        on_reasoning_delta(delta_text)
    +                    except Exception:
    +                        logger.debug("Codex stream on_reasoning_delta raised", exc_info=True)
    +            elif delta_text:
                     collected_text_deltas.append(delta_text)
                     if not has_tool_calls:
                         if not first_delta_fired:
    ```
  - `scripts/release.py`

    ```diff
    @@ -486,6 +486,7 @@
         "[redacted:email]": "Rivuza",
         "[redacted:email]": "annguyenNous",
         "[redacted:email]": "annguyenNous",
    +    "[redacted:email]": "devatnull",
         "[redacted:email]": "kylekahraman",
         "[redacted:email]": "kylekahraman",
         "[redacted:email]": "seppegadeyne",
    ```
  - `tests/run_agent/test_run_agent_codex_responses.py`

    ```diff
    @@ -629,6 +629,74 @@ def _fake_create(**kwargs):
         assert response.output == [output_item]
     
     
    +def test_consume_codex_stream_routes_commentary_phase_deltas_to_reasoning(monkeypatch):
    +    from agent.codex_runtime import _consume_codex_event_stream
    +
    +    commentary_item = SimpleNamespace(
    +        type="message",
    +        phase="commentary",
    +        status="completed",
    +        content=[SimpleNamespace(type="output_text", text="I’ll call the tool now.")],
    +    )
    +    function_item = SimpleNamespace(
    +        type="function_call",
    +        id="fc_1",
    +        call_id="call_1",
    +        name="terminal",
    +        arguments="{}",
    +    )
    +    streamed = []
    +    reasoning_streamed = []
    +
    +    response = _consume_codex_event_stream(
    +        _FakeCreateStream([
    +            SimpleNamespace(type="response.created"),
    +            SimpleNamespace(
    +                type="response.output_item.added",
    +                item=SimpleNamespace(type="message", phase="commentary"),
    +            ),
    +            SimpleNamespace(type="response.output_text.delta", delta="I’ll call the tool now."),
    +            SimpleNamespace(type="response.output_item.done", item=commentary_item),
    +            SimpleNamespace(
    +                type="response.output_item.added",
    +                item=SimpleNamespace(type="function_call"),
    +            ),
    +            SimpleNamespace(type="response.output_item.done", item=function_item),
    +            SimpleNamespace(type="response.completed", response=SimpleNamespace(status="completed")),
    +        ]),
    +        model="gpt-5-codex",
    +        on_text_delta=streamed.append,
    +        on_reasoning_delta=reasoning_streamed.append,
    +    )
    +
    +    assert streamed == []
    +    assert reasoning_streamed == ["I’ll call the tool now."]
    +    assert response.output == [commentary_item, function_item]
    +    assert response.output_text == ""
    +
    +
    +def test_consume_codex_stream_keeps_final_answer_phase_deltas(monkeypatch):
    +    from agent.codex_runtime import _consume_codex_event_stream
    +
    +    streamed = []
    +    response = _consume_codex_event_stream(
    +        _FakeCreateStream([
    +            SimpleNamespace(type="response.created"),
    +            SimpleNamespace(
    +                type="response.output_item.added",
    +                item=SimpleNamespace(type="message", phase="final_answer"),
    +            ),
    +            SimpleNamespace(type="response.output_text.delta", delta="visible answer"),
    +            SimpleNamespace(type="response.completed", response=SimpleNamespace(status="completed")),
    +        ]),
    +        model="gpt-5-codex",
    +        on_text_delta=streamed.append,
    +    )
    +
    +    assert streamed == ["visible answer"]
    +    assert response.output_text == "visible answer"
    +
    +
     def test_run_codex_stream_surfaces_failed_status_in_final_response(monkeypatch):
         """A ``response.failed`` terminal event is reflected on the returned object."""
         agent = _build_agent(monkeypatch)
    ```

    ```diff
    @@ -1156,7 +1224,7 @@ def test_run_conversation_codex_tool_round_trip(monkeypatch):
         responses = [_codex_tool_call_response(), _codex_message_response("done")]
         monkeypatch.setattr(agent, "_interruptible_api_call", lambda api_kwargs: responses.pop(0))
     
    -    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id):
    +    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id, *_args):
             for call in assistant_message.tool_calls:
                 messages.append(
                     {
    ```

    ```diff
    @@ -1347,7 +1415,7 @@ def _fake_api_call(api_kwargs):
     
         monkeypatch.setattr(agent, "_interruptible_api_call", _fake_api_call)
     
    -    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id):
    +    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id, *_args):
             for call in assistant_message.tool_calls:
                 messages.append(
                     {
    ```

    ```diff
    @@ -1382,7 +1450,7 @@ def test_run_conversation_codex_continues_after_incomplete_interim_message(monke
         ]
         monkeypatch.setattr(agent, "_interruptible_api_call", lambda api_kwargs: responses.pop(0))
     
    -    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id):
    +    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id, *_args):
             for call in assistant_message.tool_calls:
                 messages.append(
                     {
    ```

    ```diff
    @@ -1569,8 +1637,26 @@ def test_normalize_codex_response_marks_commentary_only_message_as_incomplete(mo
         )
     
         assert finish_reason == "incomplete"
    -    assert "inspect the repository" in (assistant_message.content or "")
    +    assert (assistant_message.content or "") == ""
    +    assert "inspect the repository" in (assistant_message.reasoning or "")
    +    assert assistant_message.codex_message_items
    +    assert assistant_message.codex_message_items[0]["phase"] == "commentary"
    +    assert "inspect the repository" in assistant_message.codex_message_items[0]["content"][0]["text"]
    +
    +
    +def test_normalize_codex_response_does_not_fallback_to_output_text_for_commentary_only(monkeypatch):
    +    agent = _build_agent(monkeypatch)
    +    from agent.codex_responses_adapter import _normalize_codex_response
    +
    +    response = _codex_commentary_message_response("I’ll call the tool now.")
    +    response.output_text = "I’ll call the tool now."
     
    +    assistant_message, finish_reason = _normalize_codex_response(response)
    +
    +    assert finish_reason == "incomplete"
    +    assert (assistant_message.content or "") == ""
    +    assert "call the tool" in (assistant_message.reasoning or "")
    +    assert assistant_message.codex_message_items[0]["phase"] == "commentary"
     
     def test_normalize_codex_response_final_answer_overrides_top_level_incomplete(monkeypatch):
         from agent.codex_responses_adapter import _normalize_codex_response
    ```

    ```diff
    @@ -1974,7 +2060,7 @@ def test_run_conversation_codex_continues_after_commentary_phase_message(monkeyp
         ]
         monkeypatch.setattr(agent, "_interruptible_api_call", lambda api_kwargs: responses.pop(0))
     
    -    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id):
    +    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id, *_args):
             for call in assistant_message.tool_calls:
                 messages.append(
                     {
    ```

    ```diff
    @@ -1990,11 +2076,17 @@ def _fake_execute_tool_calls(assistant_message, messages, effective_task_id):
     
         assert result["completed"] is True
         assert result["final_response"] == "Architecture summary complete."
    +    commentary_messages = [
    +        msg for msg in result["messages"]
    +        if msg.get("role") == "assistant" and msg.get("finish_reason") == "incomplete"
    +    ]
    +    assert commentary_messages
    +    assert all((msg.get("content") or "") == "" for msg in commentary_messages)
         assert any(
    -        msg.get("role") == "assistant"
    -        and msg.get("finish_reason") == "incomplete"
    -        and "inspect the repo structure" in (msg.get("content") or "")
    -        for msg in result["messages"]
    +        "inspect the repo structure" in item["content"][0]["text"]
    +        for msg in commentary_messages
    +        for item in (msg.get("codex_message_items") or [])
    +        if item.get("phase") == "commentary"
         )
         assert any(msg.get("role") == "tool" and msg.get("tool_call_id") == "call_1" for msg in result["messages"])
     
    ```

    ```diff
    @@ -2010,7 +2102,7 @@ def test_run_conversation_codex_continues_after_ack_stop_message(monkeypatch):
         ]
         monkeypatch.setattr(agent, "_interruptible_api_call", lambda api_kwargs: responses.pop(0))
     
    -    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id):
    +    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id, *_args):
             for call in assistant_message.tool_calls:
                 messages.append(
                     {
    ```

    ```diff
    @@ -2051,7 +2143,7 @@ def test_run_conversation_codex_continues_after_ack_for_directory_listing_prompt
         ]
         monkeypatch.setattr(agent, "_interruptible_api_call", lambda api_kwargs: responses.pop(0))
     
    -    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id):
    +    def _fake_execute_tool_calls(assistant_message, messages, effective_task_id, *_args):
             for call in assistant_message.tool_calls:
                 messages.append(
                     {
    ```
- **#25268: fix(agent): hide codex commentary messages**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#24933`, `#24933`
- **#41343: fix(codex): route commentary-phase preamble text to reasoning channel (fixes #41293)**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#58868`, `#58696`, `#41293`, `#24933`

## Fix status

- Merged to main in PR #58868 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-07-05`.
- Subsystem: `agent`