feat(claude): gate lossy translated Messages with bounded diagnostics

[lidge-jun]

Summary

Add an opt-in compatibility gate before translated Messages lose unsupported protocol semantics. Unset configuration preserves existing behavior; shadow records bounded evidence; enforce rejects the documented unsupported subset before inference. True native passthrough remains unchanged. Invalid configured modes return a fixed configuration error.

Use closed feature codes throughout request-log persistence and hydration. Document intentionally tolerated degradation instead of claiming lossless translation. Reimplements #3730 at source head 18d6474 with independent contract and security corrections.

Co-authored-by: SB Yoon 44089734+yansigit@users.noreply.github.com
Co-authored-by: Yumi automation@sbyoon.com

Verification

• Independent source reviews passed, including the merge of dev eff908e0f. Claude admission/persistence and diagnostic workflows received explicit independent security review. The Windows fixture changes also passed independent source review.
• Local tests, typecheck, installs and builds were not run, per maintainer instruction. Branches were pushed with --no-verify.
• Final integration CI passed all 25 jobs at exact head 4a759716a940595b999805be40d1514c100d63cf, containing all five layers plus dev eff908e0f. All expected jobs completed successfully.
• Dev advanced after final CI started to f89b815090020f52089801b50f569a777bdfdc0a. Independent source interaction review passed. That track's 25-job CI verifies its own source; its initial watchdog failure remains recorded there.
• The conflict-free combined source bf5ce1c3a0ada78f8e506334a82c64b525b859da additionally passed remote Bun 1.4.0 typecheck, 541 tests across 11 relevant files, and the 425-page documentation build. This supplements the full cross-platform run at 4a759716a; it is a focused combined-tree check, not a second complete platform matrix.
• Earlier final CI failures were investigated before changing fixtures: cache-policy controls isolated composed-fixture cold-cache costs; preparation-budget and semantic-mutation controls verified the competing-OFF allocation and retained assertion sensitivity. Shim advisory controls additionally verified an owned process deadline while retaining failure on a broken advisory collector. These diagnostics are not full integration proof.
• Automatic PR matrix runs are suppressed by commit skip directives. Lower diagnostics were used only after final-matrix failure. No skipped lower check is described as passed; diagnostic-only workflows are excluded from the delivery stack.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Manual review chain (integrate bottom-up)

Layer	PR	Review base
1	#3803	dev
2	#3804	codex/track2-protocol-foundation
3	#3805	codex/track2-canonical-efforts
4	#3806	codex/track2-refusal
5	#3808	codex/track2-claude-compatibility

Maintainer integration decision: @lidge-jun explicitly integrates this PR into dev under MAINTAINERS.md at head 4255bfac615c59602088a9af5045762067d262c2, using the final-head-first verification above and the authorized admin merge. This is maintainer integration, not a self-approval. Lower skipped checks are not passing evidence. Actor, base, head and review state are refreshed before merging.

Final integration path: #3803, #3804 and #3805 landed first. #3808 integrates the remaining Claude head and fixture repairs together. Its final history-only integration head is 9dc8988d79a29741de8a8b89bd52790c132d751e; tree eb4473dfe9e6b95072e3eb31901df635c73dd0eb exactly equals the remotely checked combined source. The full 25-job matrix is attributed to 4a759716a, and combined-tree typecheck/541 tests/docs to bf5ce1c3a; no new full-platform run is claimed for the history-only head.

Landing confirmed: included in dev 5759d9ea2f1e7281cdc01eb9628f2e0a123fb59c. All five PR heads are ancestors of fetched dev. Final tree eb4473dfe9e6b95072e3eb31901df635c73dd0eb exactly equals the remotely checked combined source. #3806 was integrated with #3808; GitHub records both as merged.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• ^dev$
• ^preview$

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 1e0946c9-16fe-4b44-aeb8-784683f69e26

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T17:36:40.585848Z	d60a071	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[lidge-jun]

리뷰 · 우선순위 52 / 80

이 PR은 Track2 맨 위 층이다. 베이스는 codex/track2-refusal(#3805), 헤드는 codex/track2-claude-compatibility다. 번역된 Claude Messages 경로에서 지원하지 않는 프로토콜 의미가 조용히 사라지기 전에, 선택적 호환 게이트를 둔다. 설정이 없으면 지금과 같고, shadow는 증거만 남기며, enforce는 문서화된 unsupported 부분집합을 추론 전에 거절한다. 진짜 native passthrough는 이 정책을 부르지 않는다. #3730을 소스 헤드 기준으로 다시 구현했고, 계약·보안 보정이 들어 있다.

현재 dev에는 src/claude/compatibility.ts가 없다. 이 PR이 새 파일로 넣고, claude-messages.ts에서 effort rewrite/번역 전에 원본 body를 검사한다. types/config.ts에 claudeCode.compatibility를 추가하고, request-log/usage-log는 닫힌 feature code만 직렬화·hydration한다. 잘못된 설정 값은 고정 configuration error(503)다. 기본값이 꺼져 있으므로 Claude 사용자를 dev에서 즉시 막지는 않는다. 그래서 우선순위는 중간(52)이다. 채팅 의미(#3803/#3805)나 카탈로그(#3804)보다 낮다.

FEATURES 맵의 불리언 의미는 이름이 헷갈릴 수 있다. 주석대로 false는 “손실을 알면서 허용”, true는 “enforce에서 거절할 unsupported”다. 테스트도 cache_control/input_examples/thinking_settings는 allow로 두고, documents/thinking_replay/hosted tools 등은 reject로 둔다. 스키마·인자·일반 function 이름 안의 문자열은 프로토콜 선언으로 보지 않는다. 진단 reason에는 caller 텍스트·헤더·모델명·도구명을 넣지 않는다. 이 부분은 보안 리뷰 포인트로 잘 막혀 있다.

스택 관점에서는 #3803→#3805가 만든 Chat/refusal 기초 위에, Claude 번역 입구의 손실을 관측/차단하는 층이다. “새 provider 추가 없음” 방향과도 맞다. types/config에 필드 한두 줄이 더해지지만, 대규모 types/config split 캠페인에 삼켜질 규모는 아니다. close-don't-rebase 대상이 아니다. 최종 CI가 이 헤드(84c94f3d77)를 검증 중이라, 이 PR이 스택 초록의 관문이다.

운영 메모: 기본 off이므로 merge만으로 행동 변화는 거의 없다. shadow를 먼저 켜서 실트래픽 코드를 모은 뒤 enforce로 가는 순서를 문서에 적어 둔 것이 좋다. #3730 원본과 무엇이 달라졌는지도 merge 노트에 한 줄 있으면 기여자에게 친절하다.

경로 src/claude/compatibility.ts FEATURES - true=거절 대상, false=허용된 손실. 이름만 보면 isSupported처럼 보여 주석/문서에 의미를 더 밝혀 두면 좋다
경로 src/server/claude-messages.ts 호환 검사 위치 - 번역/effort rewrite 전이라 원본 의미를 본다. native passthrough 앞이라 올바른 자리로 보인다
경로 request-log.ts / usage/log.ts - 닫힌 코드만 persist하는 정규화가 있다. 임의 문자열 hydration 금지
경로 types/config.ts claudeCode.compatibility - 설정 키가 작아 types split에 큰 충돌은 없어 보인다
경로 tests/claude-integration/claude-compatibility.test.ts - reject 목록이 사실상 정책 표다. 표를 바꿀 때 테스트와 문서를 같이 고쳐야 한다

메인테이너의 판단이 필요한 지점

• 허용(false)과 거절(true) 경계가 제품 의도와 맞는지 (예: cache_control 허용 vs documents 거절)
• merge 직후 기본을 계속 unset으로 둘지, shadow를 권장 기본으로 올릴지
• feat(claude): gate routed protocol compatibility #3730 관련 이슈/PR 정리 문구를 이 PR merge 시 어떻게 남길지

너의 추천
스택 헤드 CI가 초록이면 #3803→#3804→#3805 다음 마지막에 merge한다. 기본 설정은 unset 유지, 운영에서 shadow 먼저. 라벨은 바꾸지 않는다.

이 댓글은 grok-bot이 작성했습니다