fix(tools): enforce routed tool choice policy

[luvs01]

Summary

• apply one shared tool-choice predicate to routed tool advertisement and namespace/custom/tool-search restoration
• prevent excluded web-search, image, and video sidecars from arming or running paid/external work
• preserve named and allowed wire/dotted aliases while keeping the no-tools wire contract unchanged

Verification

• Bun 1.3.14: focused seven-file suite — 179 passed, 0 failed, 631 assertions
• bun run typecheck — passed
• bun run privacy:scan — passed
• git diff --check HEAD^ HEAD — passed
• full suite was not repeated because this same current-dev Windows environment already hit unrelated baseline failures and a Bun 1.3.14 panic during adjacent fix(server): bound live sideband websocket frames #1381 validation; every directly affected suite is green

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.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Tool selection settings are now consistently honored across chat, image, video, web search, and collaboration features.
  • Tools are activated only when permitted by the request, including named tools, aliases, and allowed-tool lists.
  • Selecting “none” now prevents optional tools and related bridges from activating.

• Bug Fixes

  • Prevented unselected tools from appearing in downstream tool metadata or triggering sidecar functionality.

• Tests

  • Added coverage for tool filtering across chat, image, video, web search, and response parsing scenarios.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds toolChoiceToolPredicate and applies it to chat tool formatting, tool catalogs, image and video bridges, response bridge maps, and web-search planning. Tests cover none, named tools, aliases, namespaces, and allowed-tool lists.

Changes

Tool-choice predicate and adapter filtering

Layer / File(s)	Summary
Shared predicate and chat tool filtering src/types.ts, src/adapters/openai-chat.ts, src/adapters/tool-catalog-nudge.ts, tests/reasoning-effort.test.ts	toolChoiceToolPredicate handles automatic, required, none, named, aliased, and allowed-tool choices. Chat requests and tool catalogs use the shared predicate. Tests verify omitted, named, and namespaced tool selections.

Bridge authorization

Layer / File(s)	Summary
Image, video, and response bridge filtering src/images/plan.ts, src/images/loop.ts, src/server/responses/collaboration.ts, tests/images/plan.test.ts, tests/videos/plan-video.test.ts, tests/responses-parser.test.ts	Image and video plans activate only when an authorized tool is selected. Image loops and response bridge maps exclude unauthorized tools. Tests cover excluded, named, aliased, and allowed-tool selections.

Web-search authorization

Layer / File(s)	Summary
Web-search sidecar and metadata filtering src/web-search/index.ts, src/web-search/loop.ts, tests/web-search.test.ts	Web-search planning stops when web_search is excluded. Web-search tool metadata excludes tools rejected by the request predicate. Tests cover none, unrelated tools, allowed-tool lists, explicit selection, and required selection.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Request
  participant toolChoiceToolPredicate
  participant BridgePlanning
  participant ToolMetadata
  Request->>toolChoiceToolPredicate: provide toolChoice
  toolChoiceToolPredicate-->>BridgePlanning: authorize image, video, or web-search names
  toolChoiceToolPredicate-->>ToolMetadata: authorize advertised tools
  BridgePlanning->>BridgePlanning: activate selected bridge
  ToolMetadata->>ToolMetadata: build filtered tool maps

Loading

Possibly related PRs

• lidge-jun/opencodex#424: Introduced image-bridge code modified here for shared tool-choice filtering.
• lidge-jun/opencodex#577: Added image-bridge behavior extended here with centralized authorization.
• lidge-jun/opencodex#582: Added video-bridge logic modified here to enforce toolChoice.

Suggested reviewers: ingwannu, lidge-jun, wibias

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: enforcing tool-choice policy for routed tools.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request is already Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently. If no CodeRabbit review appears, comment @coderabbitai review to request one.
Maintainers: @lidge-jun @Ingwannu @Wibias

[Wibias]

@luvs01 Please rebase your other PR's first, if not I will have to be closing the last 2 PR's of yours. Thanks in advance.

[luvs01]

@Wibias All 22 remaining open PRs have now been rebased onto the current dev@d517161a; every rewritten head was pushed and its exact-head checks were retriggered. #1374 has merged. All remaining PRs currently read back as mergeable and Draft.

#1373 is the sole exception in the lightweight gates: its code checks pass, but it awaits the maintainer-owned maintainer-sponsored and gui-screenshot-waived labels (it changes no GUI files). Thanks for the reminder.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/images/plan.ts`:
- Around line 50-53: Update the image-name handling in
src/images/plan.ts#L50-L53 to retain only names accepted by toolAllowed, adding
the synthetic image name only when authorized; update the video alias handling
in src/images/plan.ts#L114-L115 with the same filtering before returning
toolNames. In tests/videos/plan-video.test.ts#L50-L67, add coverage for
toolChoice selecting VIDEO_GEN_TOOL_NAME while generate_video is detected, and
assert generate_video is excluded from the plan.

🪄 Autofix

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: fbdac645-f8ea-493d-bd50-69684d468c86

📥 Commits

Reviewing files that changed from the base of the PR and between 4ef5350 and d1fcc65.

📒 Files selected for processing (13)

• src/adapters/openai-chat.ts
• src/adapters/tool-catalog-nudge.ts
• src/images/loop.ts
• src/images/plan.ts
• src/server/responses/collaboration.ts
• src/types.ts
• src/web-search/index.ts
• src/web-search/loop.ts
• tests/images/plan.test.ts
• tests/reasoning-effort.test.ts
• tests/responses-parser.test.ts
• tests/videos/plan-video.test.ts
• tests/web-search.test.ts

[coderabbitai]

An unexpected error occurred while generating fixes: Not Found - https://docs.github.com/rest/git/refs#get-a-reference

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@github-actions[bot] Acknowledged. PR #1382 is marked ready for review, and the reported quality gates have passed.

_{You are interacting with an AI system.}

[coderabbitai]

@github-actions[bot] The PR gate is complete. I will review pull request #1382.

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

@github-actions[bot] The readiness gate for PR #1382 is complete. I will review the pull request.

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@github-actions[bot] Acknowledged. PR #1382 is Ready for Review. The quality-gate status is recorded.

_{You are interacting with an AI system.}

[luvs01]

Exact-head CI is blocked only by the macOS native profile OpenCodex process-exit phases test; every changed image/video plan test and all other required jobs passed. I attempted a failed-job rerun, but GitHub requires repository admin rights. Please rerun the failed macOS job when convenient: https://github.com/lidge-jun/opencodex/actions/runs/31346444665

[Wibias]

Reviewed the current head. The shared tool-choice predicate is applied consistently across advertisement, restoration, and sidecar planning, including the previously reported media-alias gap. The affected CI is green and I found no remaining blocking issue. This is a useful safety fix because tool_choice now acts as an actual execution boundary, so excluded tools cannot leak into metadata or trigger paid/external sidecar work.

[Wibias]

Thanks @luvs01 for this fix. 🙏 This is especially useful because it turns tool_choice into a consistent execution boundary, not just an advertisement hint: excluded web-search, image, video, namespace, custom, and tool-search paths can no longer be restored or armed accidentally. That reduces surprising external/paid work and keeps routed behavior aligned with the caller's explicit tool policy. Merged, thank you!