Skip to content

fix(crag): lift inline tool_definition additions into top-level tools (#1118) - #1128

Closed
panjinhe wants to merge 2 commits into
dofastted:mainfrom
panjinhe:fix/crag-inline-tool-definition
Closed

panjinhe wants to merge 2 commits into
dofastted:mainfrom
panjinhe:fix/crag-inline-tool-definition

Conversation

@panjinhe

Copy link
Copy Markdown
Contributor

Fixes #1118

Problem

Claude Code 2.1.325 adds a tool mid-conversation with an inline definition:

{"type": "tool_addition", "tool": {"type": "tool_definition", "definition": {"name": "...", "input_schema": {}}}}

CRAG 3.0.7 only understands tool.type: "tool_reference" and rejects this with 400 tool_addition requires a tool name. The block stays in history, so every later turn of that session fails and the user has to start a new session. Additions with tool_reference were always fine.

A second, smaller bug showed up on the third-party path. Tools get renamed to mcp__*, but a tool_addition / tool_removal tool_reference kept the bare name, so it pointed at a tool the request no longer declared.

Fix

  • crag-print-prompt.mjs: liftInlineToolDefinitions runs first in prepareCragPrintBody. Each inline definition is added to top-level tools, and the block is rewritten to {type: "tool_reference", name}. A tool that is already declared is not duplicated, and the caller body is not mutated.
    • The lifted tool is a plain tool, not defer_loading. Through CRAG, a deferred tool that a tool_reference addition points at was not reliably offered to the model (0/3 calls deferred, 3/3 plain). The cost is one tools-prefix cache rewrite, on the turn the tool is added.
    • The gateway eager_input_streaming policy has already run on the declared tools by this point. A lifted tool is marked eager only when every declared custom tool is eager; otherwise CRAG does not offer the model a non-eager tool next to eager ones.
  • anthropic-policy.mjs: tool_addition / tool_removal references are renamed along with their tools.

This is a workaround until the kernel accepts tool_definition. Remove liftInlineToolDefinitions once it does. The rename fix is independent and should stay.

Tests

  • crag-print-prompt.test.mjs: lift into top-level tools, no duplicates, tool_reference and declared tools left alone, eager policy.
  • anthropic-policy.test.mjs: addition/removal references follow the mcp__ rename.
  • Full unit suite passes on this branch.

Verified in production

Running since 2026-11-16 on 1.4.112 with both files mounted. A replayed session carrying an inline tool_definition returns 200 and the model calls the lifted tool (3/3).

…dofastted#1118)

CRAG 3.0.7 only understands tool_addition with tool.type tool_reference and
rejects Claude Code 2.1.325's inline tool_definition with 400 "tool_addition
requires a tool name". The block stays in history, so every later turn of the
session fails.

Before print, lift each inline definition into top-level tools and rewrite the
block to a tool_reference by name. A tool already declared is not duplicated.
The lifted tool is plain (not deferred): through CRAG a deferred tool named by
a tool_reference addition was not reliably offered to the model (0/3 deferred,
3/3 plain). It follows the gateway eager_input_streaming policy when every
declared custom tool is eager.
…h their tools

Third-party clients get their tools renamed to mcp__*, but a mid-conversation
tool_addition/tool_removal tool_reference kept the bare name and pointed at a
tool the request no longer declared.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T12:04:21.563124Z 29f0e55 PR opened
ℹ️ 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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 29f0e55576

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +725 to +727
const name = rename(block.tool.name)
if (name === block.tool.name) return { block, changed: false }
return { block: { ...block, tool: { ...block.tool, name } }, changed: true }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Rename tool-change references only with their declarations

For third-party cli-node/direct-API requests with tool-name rewriting enabled, inline definitions are still forwarded unchanged: a history that adds inline Artifact and later removes it now retains definition name Artifact but changes the removal to mcp__Artifact. Native tools have the same problem: scrubUpstreamClientBody deliberately leaves a declared web_search unchanged, while this branch changes its addition/removal references to mcp__web_search. These references no longer target the tools actually declared. Reuse mappings for declarations that were actually renamed, or rename the inline definitions consistently as well.

Useful? React with 👍 / 👎.

Comment on lines +421 to +424
const definition = block.tool.definition
if (!known.has(definition.name)) {
known.add(definition.name)
const tool = { ...definition }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Deduplicate inline definitions in the normalized tool-name namespace

For third-party CRAG requests, handle-protocol.mjs calls toStandardAnthropicBody before this helper, so a top-level Artifact is already named mcp__Artifact, while its inline definition still says Artifact. This lookup misses the existing declaration, and the final scrub produces both mcp__Artifact and mcp__Artifact_2. Replaying this pipeline with a later removal makes the inline addition reference _2, but the previously normalized removal still references the unsuffixed tool, leaving the duplicate available after removal. Lift before renaming or resolve inline names through the same mapping before deduplicating.

Useful? React with 👍 / 👎.

@dofastted

Copy link
Copy Markdown
Owner

CRAG 3.1.4 已原生接受并保留 system 内联 tool_definition 及相应移除,不再需要提升到顶层 tools 的 workaround。官方 Claude Code 2.1.321 回环已验证。第三方路径对 tool_addition / tool_removal 的 mcp__* 引用改名未由本版覆盖,PR 保留;建议只保留独立改名部分评审。见 Release 与 #1160。

@dofastted

Copy link
Copy Markdown
Owner

感谢贡献。替代修复 #1162 已合入 main(1881d65f01)。CRAG 3.1.4 原生支持内联工具增删;面板只修第三方工具引用名称一致性,不提升原生内联定义。 此 PR 不再重复合并。

@dofastted dofastted closed this Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants