feat(codex): capture encrypted reasoning and replay it only to its issuer

[mabry1985]

Follow-up to #3199, which closed the bleeding but left cross-turn reasoning continuity on openai-codex off. This turns it on, plus the guard that makes it safe on a thread that can move between providers.

Capture

langchain-openai's streaming Responses path has no response.output_item.done branch for reasoning — it has one for compaction, which carries the same kind of blob — and the terminal response.completed event rebuilds the full message but keeps only parsed/usage/response_metadata. So encrypted_content is visible in exactly one event, which the converter drops on the floor:

added -> [{'id': 'rs_1', 'summary': [], 'type': 'reasoning', 'index': 0}]
done  -> None          # …and this event is the one carrying encrypted_content

_install_reasoning_capture re-emits that event as a content-block delta that merges onto the reasoning block already in flight, by index — the way every other streamed block merges. The wrapper sits on the shared module-level converter (there is no instance seam) but is inert unless a contextvar this module's client sets is present, so a gateway client or any other Responses user in the process goes through the original code path unchanged. That's covered by a test.

output_version → responses/v1

This is the follow-up the v0 pin was explicitly holding open. v0 collapses a turn's reasoning into one additional_kwargs slot: later items overwrite earlier ones, and streamed fragments of two different items merge into each other — it structurally cannot carry per-item blobs. responses/v1 keeps each item as its own block, in order, and langchain replays them that way natively:

{'type': 'reasoning', 'summary': [...], 'encrypted_content': 'BLOB1'}
{'type': 'function_call', 'name': 't', 'call_id': 'c1', ...}
{'type': 'reasoning', 'summary': [], 'encrypted_content': 'BLOB2'}
{'type': 'message', 'role': 'assistant', 'content': [...]}

The rendering half of the pin was already paid off — every answer site reads AIMessage.text, which yields text blocks only (verified). One gap did surface: text_of (which feeds exports, session memory and chat bundles — all of which persist what they read) rendered a reasoning block as _[reasoning]_. It now skips reasoning outright, which is what ADR 0021 asks for anyway. PROTOAGENT_CODEX_OUTPUT_VERSION=v0 is the escape hatch back to the string shape.

Issuer stamping

encrypted_content is sealed to the endpoint and account that minted it, and this repo lets every slot name its own connection, each chat tab override the model per turn, and a failed turn retry against the fallback chain. So each captured item carries issuer_fingerprint(base_url, account_id) — a truncated digest, so a checkpoint never stores a raw account id — and replay drops items stamped with a different issuer. Unstamped items (checkpointed before this) still replay.

This is what makes mixing providers on one thread a continuity cost rather than a 400: without it, #3199's recovery middleware would be firing routinely instead of never.

Outbound rules, now complete

Item	Action
no blob	drop (#3199 — a ghost the backend can't verify)
foreign issuer	drop (this endpoint can't decrypt it)
unstamped + blob	replay (pre-existing threads keep working)
ours + blob	replay, minus id and our private keys

Verification

• tests/test_codex_reasoning_capture.py — 19 tests driving real OpenAI event types through the real converter and the real chunk merge: blob lands on the right block, two items keep their own blobs in order, wrapper inert without the contextvar, idempotent install, fingerprint separation + no account-id leak, all four replay rules, capture→replay end to end, a foreign thread sending nothing, and a legacy v0 message in the same thread still sending no ghost.
• Full suite 6700 passed, 15 skipped · ruff clean · lint-imports 3/3 · live_smoke.py PASSED.
• Docs: ADR 0097 section + open-item rewrite, configuration.md tip on mixing providers mid-thread, both env vars in environment-variables.md.

What is not verified

No turn has been driven against a real ChatGPT subscription with this on — the wire shape is tested exhaustively, the backend's acceptance of it is not. If the backend objects, #3199's CodexReasoningReplayRecoveryMiddleware strips the replay state and retries, so a thread degrades to stateless continuity rather than breaking. That ordering was deliberate.

Worth an upstream issue as well: langchain-openai should handle output_item.done for reasoning items the way it already does for compaction, which would let us drop the converter wrapper entirely.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 14 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: db844cd2-f5bf-400d-812d-81a41d0ad4fb

📥 Commits

Reviewing files that changed from the base of the PR and between ad4ff54 and 86d67ac.

📒 Files selected for processing (8)

• changelog.d/3207.added.md
• docs/adr/0097-native-oauth-subscription-providers.md
• docs/reference/configuration.md
• docs/reference/environment-variables.md
• graph/message_blocks.py
• graph/providers/codex_client.py
• graph/providers/openai_codex.py
• tests/test_codex_reasoning_capture.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[protoreview]

QA panel review — PASS

code-review-structural · head 66f791bc9473 · formal

⚠️ PR advanced 1 commit(s) during this round (66f791bc9473 → 5e318bfb2333); 0 finding(s) in the delta were demoted to possibly addressed.

Overall risk is low: the panel surfaced a single nit (a docstring that calls the issuer stamp "salted" when it is a plain truncated SHA-256). Fix-first: align the docstring wording with the ADR already in the same PR ("a truncated digest"). The panel did not disagree on anything — the verifier confirmed the one finding without modification. Verification changed nothing: no findings were refuted or downgraded. Coverage gap: the panel produced only one finding across the entire PR; if other production files were touched in this diff, they went under-read by the finders.

Findings

	Severity	Location	Finding	Verified
⚪	nit	graph/providers/codex_client.py:34	The module docstring describes the issuer stamp as 'a salted digest', but issuer_fingerprint is an unsalted SHA-256 (no salt is mixed in), so the docstring ove…	confirmed

findings JSON (machine-readable)

[
  {
    "file": "graph/providers/codex_client.py",
    "line": 34,
    "severity": "nit",
    "category": "conventions",
    "claim": "The module docstring describes the issuer stamp as 'a salted digest', but issuer_fingerprint is an unsalted SHA-256 (no salt is mixed in), so the docstring overstates the implementation.",
    "evidence": "Docstring: \"the same design (`_classify_responses_issuer`); the stamp is a salted digest so a\\ncheckpoint never stores a raw account id.\" vs. the code: \"raw = f\\\"{(base_url or '').strip().rstrip('/')}\\\\x00{(account_id or '').strip()}\\\"\\n    return hashlib.sha256(raw.encode()).hexdigest()[:16]\" \u2014 no salt. The ADR the same PR writes says only 'a truncated digest', which is accurate.",
    "verdict": "confirmed",
    "note": "Verified in the diff: the new docstring says 'a salted digest' but issuer_fingerprint is plain SHA-256 of base_url+account_id with no salt; the ADR in the same PR correctly says 'a truncated digest'. Quotes match the diff verbatim."
  }
]

[mabry1985]

Pushed a correctness fix found while re-verifying, worth calling out because the original tests did not catch it.

The contextvar that gates the capture was armed in an override of _stream_responses. But ChatOpenAI._stream routes with super()._stream_responses(...) — an explicit super(ChatOpenAI, self) bind that skips right past the subclass. So the override was dead code: the capture would never have armed in production, while every unit test that set the contextvar itself still went green.

Armed on _stream/_astream instead (dispatched on the instance), and added test_capture_arms_on_the_real_stream_path, which drives the client's own stream against a stubbed root_client so nothing but the client can set the contextvar. Confirmed it fails against the old seam (KeyError: 'encrypted_content') before passing against the new one.

[protoreview]

QA panel review — PASS

code-review-structural · head 87c13eac77a7 · formal

Clean final pass. The panel's sole finding (the "salted digest" docstring inaccuracy at graph/providers/codex_client.py:34) was a nit adjudicated in round 1 with a PASS verdict and is correctly suppressed here. The verifier confirmed an empty array — no blockers, majors, or minors survive. No prior blockers or majors required disposition. No coverage gaps: the change is small and the single file touched was read by the conventions finder; the structural pass produced no additional findings.

No findings — the review came back clean.

findings JSON (machine-readable)

[]

[protoreview]

QA panel review — PASS

code-review-structural · head 86d67ac9cd20 · formal

Overall risk is low: the panel produced no confirmed defects across its lanes, and the verifier confirmed the findings array is empty. There is nothing to fix first. The panel did not disagree on any point. What verification changed: nothing — the verifier received an empty array and confirmed there was nothing to ground, refute, or mark uncertain. One gap worth flagging: the structural pass (code-review-structural) delivered zero findings to the verifier, which is ambiguous between "clean" and "skipped." Additionally, the verifier noted a coverage concern — every reader of AIMessage.content that expects a plain string may break under the new structured-block shape — but this was never submitted as a concrete finding with a cited file, line, and expected-vs-actual shape, so it cannot gate the merge in this round. If that gap is a real merge concern, it needs to be re-submitted as a grounded finding in a future round.

No findings — the review came back clean.

findings JSON (machine-readable)

[]

[protoreview]

Promoting the PASS verdict for head 86d67ac9cd20: all checks terminal-green, zero unresolved review threads. (approve-on-green)