[Ingwannu]

Summary

• Closes Native Anthropic passthrough drops anthropic-ratelimit-* headers, so Claude Code statusLine rate_limits is missing #6297: relay upstream anthropic-ratelimit-* response headers through native Anthropic SSE, JSON, error, and count-tokens responses so Claude Code statusLine consumers can observe available quota metadata.
• Forward only that header family, not cookies or unrelated upstream metadata. Missing observations are not fabricated. Existing status/body, content type, retry-after, stream guards, and account/retry behavior are unchanged.
• Add behavioral regressions and update the Claude client contract and user-facing guide. The reporter's proposed direction is credited in the commit trailer.

Verification

• Before the fix: the SSE, JSON, and 429 ingress regressions all failed because the utilization header was missing (3 failures).
• After the fix, Bun 1.4.0 on Linux: bun test tests/claude-integration/claude-native-rate-limit-headers.test.ts tests/claude-integration/claude-native-passthrough.test.ts tests/test-layout.test.ts tests/test-layout-tooling.test.ts tests/ci-workflows/file-size-ratchet.test.ts tests/ci-workflows/structure-ssot.test.ts — 141 pass, 0 fail, 1377 assertions. The new regression file covers SSE, JSON, 429, count_tokens, absence, and the header-family allowlist.
• Node 24.16.0: node --max-old-space-size=768 node_modules/typescript/bin/tsc --noEmit — pass, 33 seconds, 1.2 GiB peak memory, no swap.
• Both workloads used fresh temporary HOME/CODEX_HOME/OPENCODEX_HOME/TMPDIR and one systemd user cgroup at a time: CPUQuota=75%, MemoryHigh=1280M, MemoryMax=1536M, MemorySwapMax=0, TasksMax=64, IOWeight=20, nice=10, finite runtime limits. Tests use a synthetic owned upstream; no live account traffic or service restart.
• git diff --cached --check — pass. New files remain owned/readable by ubuntu, the execution account.
• Full suite and docs-site build deferred locally under the documented resource exception: this shared host previously required reboot after an unbounded build. Exact-head hosted Cross-platform CI run 36818611817 has now completed successfully, including all four test shards, gates, docs-site build, structure gate, packaging and smoke jobs. Scope-gated full Windows/macOS runtime lanes were not selected; they are not claimed as validated. No local security scan was run. No real Claude Code statusLine/account end-to-end test or Windows/macOS runtime validation is claimed.

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.

The final review checkbox is intentionally left for independent maintainer review; this PR does not self-approve or waive required checks. Please review the narrow response-header allowlist and the retained native passthrough contract.

Summary by CodeRabbit

• New Features
  • Native Anthropic passthrough now preserves upstream rate-limit headers on streaming, JSON, and error responses, helping clients see the rate-limit information provided by Anthropic.
  • Only Anthropic rate-limit headers are forwarded; missing headers are not created, and unrelated headers are not relayed.
• Documentation
  • Updated Claude integration guides to describe rate-limit header forwarding.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

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

Next included review available in 19 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 60153c6d-f957-4dae-a8b8-7ddeed80f695

📥 Commits

Reviewing files that changed from the base of the PR and between eaadb51 and 54e870d.

📒 Files selected for processing (7)

• docs-site/src/content/docs/guides/claude-code.md
• scripts/test-layout/layout.json
• src/server/anthropic-rate-limit-headers.ts
• src/server/claude-messages.ts
• structure/clients/claude-desktop.md
• tests/claude-integration/claude-native-rate-limit-headers.test.ts
• tests/fixtures/test-layout-expected.json

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 038a55b7-64a2-45d1-b694-be8c2da0e8a6

📥 Commits

Reviewing files that changed from the base of the PR and between 6429463 and eaadb51.

📒 Files selected for processing (7)

• docs-site/src/content/docs/guides/claude-code.md
• scripts/test-layout/layout.json
• src/server/anthropic-rate-limit-headers.ts
• src/server/claude-messages.ts
• structure/clients/claude-desktop.md
• tests/claude-integration/claude-native-rate-limit-headers.test.ts
• tests/fixtures/test-layout-expected.json

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The native Anthropic passthrough now preserves upstream anthropic-ratelimit-* headers in streaming and non-streaming responses. Tests cover message and count-token relays, including upstream errors. Documentation describes the forwarded headers and unchanged response behavior.

Changes

Native Anthropic passthrough

Layer / File(s)	Summary
Filter and forward rate-limit headers src/server/anthropic-rate-limit-headers.ts, src/server/claude-messages.ts, tests/claude-integration/claude-native-rate-limit-headers.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json, docs-site/src/content/docs/guides/claude-code.md, structure/clients/claude-desktop.md	A new helper selects upstream anthropic-ratelimit-* headers. The passthrough includes them in streaming and non-streaming responses. Integration tests cover SSE, JSON, upstream 429, count-token responses, missing headers, and unrelated-header exclusion. Documentation describes the behavior.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to eaadb

The change preserves upstream Anthropic quota headers without forwarding unrelated headers or altering existing response behavior. No actionable merge-blocking risk is identified; merge after normal checks pass.

Security Architecture Review

Security architecture risk: 🔵 Low · up to eaadb

The change narrowly exposes upstream quota metadata through existing response paths. The header-family filter excludes cookies and unrelated metadata, and no new production route or weakened authorization control was identified. Broader access-control and deployment coverage remains incomplete.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The incremental exposure is upstream quota metadata returned to callers already reaching the native response path. The inspected change adds no credential authority, destination selection, or persistent data access; it does not establish tenant-level isolation beyond the existing access controls.

Trust Boundaries and Controls

• observed — Upstream-controlled response metadata crosses into the client response through an explicit name-prefix filter rather than wholesale header forwarding. Existing native eligibility and credential checks precede passthrough, while request headers continue through the existing forwarding policy.

Resilience and Maintainability Implications

• observed — The inspected delta leaves existing cancellation, stall, and overflow outcomes intact. Header observations are request-local and are not cached or reused across requests, avoiding a new cross-request ownership or cleanup obligation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (4 skipped: 4 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #6297 requires native Anthropic passthrough to relay upstream anthropic-ratelimit-* headers without changing response behavior. src/server/anthropic-rate-limit-headers.ts:1-6 filters the ups…
Out of Scope Changes check	✅ Passed	The changes stay within Issue #6297. The new helper and passthrough integration implement header forwarding. The new integration tests and test-layout entries support that behavior. The documentation …
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: relaying native Anthropic rate-limit headers through Claude responses.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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.

[lidge-jun]

Maintainer integration record (MAINTAINERS.md, dev only)

• Exact head: 54e870d7319be7a84933c8cb939723ad92b97fc3. The previous head eaadb51490 conflicted with dev after fix(claude): log a stalled or over-cap passthrough stream as a 502 incomplete row #6354, so the maintainer lane merged origin/dev (459b4ec16f) into the branch without a force push. The one conflict, in structure/clients/claude-desktop.md, was resolved by keeping both paragraphs. The dev → head diff contains only the PR's 7 files (+93/-1).
• Hosted CI at this head: Cross-platform CI run 36867942701 passed on attempt 1 (pull_request). Every job that ran passed: test 1/4 through test 4/4, gates, structure gate, storage policy, docker smoke, api usage, docs site build, keyring, npm-global and ci. React Doctor run 36867942899 passed, and hygiene passed (run 36867942407). Enforce PR target run 36867942603 is still in the runner queue at the time of writing. The pre-merge head eaadb51490 had passed run 36818611817.
• Local suites were not run, on the project owner's explicit instruction. Hosted CI is the only execution evidence.
• Security review (response-header relay): an independent review returned PASS at eaadb51490. A fresh re-attestation after the merge returned VERDICT: PASS — HEAD 54e870d. It confirmed that fix(claude): log a stalled or over-cap passthrough stream as a 502 incomplete row #6354's new locally generated 499/504/502 responses carry no upstream headers. Only the lowercased anthropic-ratelimit-* family is forwarded, and Content-Type is applied after it. set-cookie, auth headers, anthropic-request-id and x-ratelimit-* are asserted absent. The native passthrough uses the caller's own credential and makes one fetch, so the relayed quota always belongs to that credential.
• Findings: no P0–P2. The structure doc's "three" response shapes is corrected to "four" in the merge resolution. One non-blocking P3 remains: the docs-site paragraph sits under the OAuth-pool heading.
• Resolves Native Anthropic passthrough drops anthropic-ratelimit-* headers, so Claude Code statusLine rate_limits is missing #6297.
• Attribution: author @Ingwannu. The commit carries a co-author, @lhj6102, which the squash keeps.