fix(claude): preserve hosted web search choices

[Ingwannu]

Summary

• keep explicitly disabled Claude thinking as reasoning: { effort: "none" } without the upstream-invalid summary: "none"
• translate forced Claude WebSearch/web_search choices to the hosted Responses { type: "web_search" } shape so they match the translated hosted tool declaration
• admit the current hosted web-search choice in the Responses request schema
• document the exact mapping in all maintained Claude Code guide locales

Root cause

The Claude inbound translator reused the internal/catalog none summary sentinel on the OpenAI wire, where reasoning.summary accepts only auto, concise, or detailed. The same translator converted a Claude hosted web-search declaration to { type: "web_search" } but converted its named forced choice to { type: "function", name: "web_search" }. OpenAI therefore received a choice that could not match any declared function.

Contract boundary

The patch repairs the known hosted mapping at translation time and preserves ordinary named function choices unchanged. It deliberately does not downgrade arbitrary unmatched forced choices to auto, because that would silently relax the caller's required-tool intent and could select a different tool.

Verification

• bun test tests/claude-inbound.test.ts: 28 passed, 0 failed
• the new regression passes both responsesRequestSchema and the real parseRequest boundary
• bun run typecheck: passed
• bun run privacy:scan: passed
• docs production build: 221 pages
• git diff --check: passed

Closes #1426

Summary by CodeRabbit

• New Features
  • Added support for translating Claude WebSearch selections into hosted Responses web-search tools.
  • Added support for recognizing hosted web_search tool choices.
• Bug Fixes
  • Disabled thinking now sends only reasoning.effort: "none" without an unnecessary summary field.
• Documentation
  • Updated Claude Code guidance and localized documentation to reflect the revised reasoning and web-search mappings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f8ddc440-6fb0-4c1b-a689-a12d607b7368

📥 Commits

Reviewing files that changed from the base of the PR and between 7779c05 and d889767.

📒 Files selected for processing (8)

• docs-site/src/content/docs/guides/claude-code.md
• docs-site/src/content/docs/ja/guides/claude-code.md
• docs-site/src/content/docs/ko/guides/claude-code.md
• docs-site/src/content/docs/ru/guides/claude-code.md
• docs-site/src/content/docs/zh-cn/guides/claude-code.md
• src/claude/inbound.ts
• src/responses/schema.ts
• tests/claude-inbound.test.ts

---

📝 Walkthrough

Walkthrough

Claude inbound translation now emits valid disabled-thinking reasoning and maps forced Claude WebSearch choices to Responses web_search choices. The Responses schema, tests, and Claude Code documentation reflect these mappings.

Changes

Claude Responses translation

Layer / File(s)	Summary
Translation and schema contracts src/claude/inbound.ts, src/responses/schema.ts	Disabled thinking emits reasoning: { effort: "none" } without summary. Recognized Claude WebSearch choices map to { type: "web_search" }; other named tools remain function choices. The hosted tool schema accepts web_search.
Translation validation tests/claude-inbound.test.ts	Tests update disabled-thinking expectations and cover WebSearch conversion, reasoning preservation, schema validation, and parser validation.
Localized Claude Code documentation docs-site/src/content/docs/.../guides/claude-code.md	English, Japanese, Korean, Russian, and Simplified Chinese guides document the reasoning and WebSearch mappings.

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

Sequence Diagram(s)

sequenceDiagram
  participant ClaudeDesktop
  participant ClaudeInbound
  participant ResponsesSchema
  ClaudeDesktop->>ClaudeInbound: Send disabled thinking and forced WebSearch choice
  ClaudeInbound->>ClaudeInbound: Set reasoning effort to none
  ClaudeInbound->>ClaudeInbound: Map choice to web_search
  ClaudeInbound->>ResponsesSchema: Validate translated request
  ResponsesSchema-->>ClaudeInbound: Accept request

Loading

Possibly related PRs

• lidge-jun/opencodex#383: Shares the Claude WebSearch tool-name handling.
• lidge-jun/opencodex#954: Shares Claude inbound translation and disabled-thinking reasoning behavior.
• lidge-jun/opencodex#626: Shares changes to Claude inbound translation tests.

Suggested labels: review-ready

Suggested reviewers: lidge-jun, wibias

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR satisfies disabled-thinking and hosted WebSearch requirements in #1426, but it omits unmatched function tool-choice sanitization in src/adapters/openai-responses.ts.	Implement and test unmatched function tool-choice sanitization in src/adapters/openai-responses.ts before upstream dispatch, or update #1426 if that requirement is out of scope.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: preserving hosted WebSearch tool choices in Claude translation.
Out of Scope Changes check	✅ Passed	All code, tests, schema updates, and localized documentation changes support the Claude translation fixes requested in #1426.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/fix-1426-claude-web-search

---

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.

[Ingwannu]

Refreshed this branch onto current dev 7779c0574; the exact head is now d8897672e.

The previous macOS failure was a single unrelated full-suite timeout in chat-completions replay copy overflow returns JSON 413 after 10,679 tests had passed. No assertion in this PR's Claude/web-search changes failed. The refreshed head now has a new exact-head CI run.

Local verification after the rebase:

• bun test tests/claude-inbound.test.ts — 28 passed, 0 failed
• bun run typecheck — passed
• bun run privacy:scan — passed
• docs-site production build — 221 pages
• git diff --check — passed

@Wibias please review the exact head after CI completes.

[Wibias]

Thanks @Ingwannu — this was useful because it fixed a real Claude→Responses wire mismatch: disabled thinking was emitting an invalid reasoning.summary: "none", and forced WebSearch choices were translated as ordinary function picks that could not match the hosted { type: "web_search" } declaration. Keeping ordinary named function choices unchanged preserves required-tool intent while unblocking hosted web search.

Merging now.