Skip to content

fix(llm): retry invalid tool call arguments - #5101

Open
sailist wants to merge 4 commits into
release/2026-11-19from
bug-395-11-18-tool-call-args-retry-release
Open

sailist wants to merge 4 commits into
release/2026-11-19from
bug-395-11-18-tool-call-args-retry-release

Conversation

@sailist

@sailist sailist commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

Requirement or Bug

Sessions containing malformed, truncated, or non-object tool-call arguments can become stuck in repeated provider 400 errors, including after session restore and /compact. This PR rejects invalid arguments before tool execution, retries with clean feedback, and removes invalid historical calls from model requests so affected sessions can continue.

No issue was provided; the problem, reproduction, and root cause are documented below.

Bug Reproduction Steps

  1. Return a tool call whose arguments are truncated, for example {"command":, or a valid JSON non-object such as null, [], or 42.
  2. Existing journal code saves either the parsed value or the original string, while both restore folds unconditionally call JSON.stringify on the saved value. Empty strings and truncated fragments therefore lose their original wire form.
  3. Anthropic lowering also replaces parse failures and empty arguments with {} and accepts valid JSON non-objects without an object guard. Requests and restored history can therefore carry invalid tool_use.input, causing persistent provider 400 responses that /compact cannot repair.

The included TUI e2e play scripts a truncated Bash call, a valid retry, and two consecutive invalid responses. The candidate retries with invalid_tool_arguments, executes only the valid call, and stops after the configured second failed attempt.

Root Cause

There are two independent root causes:

  • Journal and restore disagree on argument representation, causing double-encoded strings during history reconstruction.
  • Completed model tool calls and historical messages lack a shared argument-validation boundary. Anthropic additionally hides invalid JSON behind a fabricated empty object.

This is a fundamental fix across the shared LLM, journal, and protocol paths, not an Anthropic-only workaround.

Code Changes

Core flow:

completed tool-call → shared JSON/object/schema validation
                    → invalid_tool_arguments → clean assistant feedback → retry

resolved history → remove invalid calls and paired results → protocol encoding

journal strings → restore without re-encoding → valid call or plain failure text
  • Add shared tool-argument parsing and AJV validation, including deferred tool descriptions and schema-gated empty arguments.
  • Validate at tool-call-end, return retryable invalid_tool_arguments, and retry with assistant-only failure text rather than the rejected call.
  • Clean invalid historical calls and paired tool results in the common request path used by normal turns, restore, replay, and compaction while preserving valid calls and text.
  • Preserve valid journal object representations, keep raw invalid strings with argsError, and share restore behavior between both folds.
  • Reject non-object Anthropic inputs explicitly instead of silently replacing invalid arguments with {}.
  • Update error mapping, retry logging, and English/Chinese LLM documentation.
  • Add a patch changeset for @moonshot-ai/kimi-code.

Start with packages/core/src/llm/tool-arguments.ts, then policy/settle.ts, policy/policy.ts, and the two journal fold implementations.

Behavior Changes and Affected Users

Behavior Before After Who relies on the old behavior Escape hatch
New malformed tool-call arguments Invalid calls can reach execution or produce repeated provider errors invalid_tool_arguments triggers a clean retry; exhausted attempts fail without executing the call CLI/TUI and SDK-driven turns across providers Existing maxAttemptsPerStep, abort, and explicit infinite-retry configuration
Invalid calls already in a session Restore/replay/compaction can resend them indefinitely Invalid calls and paired results are excluded from model requests and replaced with plain failure text Users continuing older sessions or compacting them Original journal remains available for diagnosis; no execution retry
Valid object arguments and mixed history Existing execution and request behavior Unchanged, including valid calls and assistant text in the same message All existing sessions and tool executors Not needed
Empty arguments Some paths convert them to {} unconditionally Accepted only when the resolved schema accepts {} No-argument tools and models emitting empty arguments A schema that explicitly permits a no-argument call
Anthropic non-object or malformed input Invalid JSON may become {}; valid non-objects may reach the provider Local explicit rejection; tool_use.input is always an object Anthropic and OpenAI-to-Anthropic conversion paths Common request cleanup prevents known invalid history; direct lowering fails explicitly
Unknown tools with JSON-object arguments Existing behavior Preserved; lack of a tool description alone is not treated as invalid arguments Hosts and older history without current tool descriptions Existing executor-side unknown-tool handling

Coverage includes deferred schemas, truncated JSON, non-objects, empty-argument acceptance/rejection, mixed valid/invalid history, retry request contents, non-streaming replay, journal restore, replay fold, compaction, Anthropic lowering, and resume consistency.

Screenshots / Recordings

TUI e2e invalid-tool-arguments was run against the candidate and the installed baseline. Captured frames show:

  1. Retrying (2/2) · invalid_tool_arguments with “Bash was not executed”.
  2. One valid command followed by RECOVERY_REPLY.
  3. The second consecutive invalid response ending in a visible provider error instead of another tool execution.

The candidate completes five main requests; the baseline completes six through the old tool-error path. Both plays and the intentional diff pass.

Verification

  • Core: 17 files, 176/176 tests passed.
  • Agent core v2 related suites: 14 files, 290/290 tests passed.
  • @moonshot-ai/core and @moonshot-ai/agent-core-v2 typechecks passed.
  • Standard pnpm lint passed, including comments, oxlint, import boundaries, guards, instructions, and ratchet checks.
  • TUI e2e candidate and baseline passed; runner typecheck passed.

Checklist

  • I have read the CONTRIBUTING document.
  • No issue was provided; this PR includes the reproduction and root cause above.
  • I have added tests that prove the fix works.
  • The behavior-change table above is complete; valid behavior is preserved and no new escape hatch is required for rejecting invalid calls.
  • Added the required patch changeset according to the repository changeset rules.
  • Updated the English and Chinese LLM design documentation for the new behavior.

Validate completed tool calls before execution and retry with clean feedback.
Remove invalid historical calls and preserve raw journal argument strings.
Guard Anthropic tool inputs against non-object arguments.
@changeset-bot

changeset-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: a327572

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
@moonshot-ai/kimi-code Patch
@moonshot-ai/kimi-code-sdk Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 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-19T11:34:25.290256Z a327572 New commits
ℹ️ 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.

@pkg-pr-new

pkg-pr-new Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
pnpm dlx https://pkg.pr.new/@moonshot-ai/kimi-code@a327572
npx https://pkg.pr.new/@moonshot-ai/kimi-code@a327572

commit: a327572

@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: 735675bb7e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread packages/core/src/llm/tool-arguments.ts Outdated
Comment on lines +145 to +146
const tool = tools.find((entry) => entry.name === call.name);
const issue = parseLlmToolArguments(call.arguments, tool).issue;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Preserve historical calls across tool-schema changes

For MCP users resuming a session after a tool is updated, removed, or disconnected, this validates previously successful calls against the current tool definition rather than the schema under which they executed. A newly required parameter makes an old call fail schema validation, while a no-argument call becomes unknown_tool when its definition is absent; cleanToolCallHistory then removes both the call and its real result and replaces them with misleading failure text. Restrict historical cleanup to schema-independent malformed/non-object checks unless the original schema snapshot is available.

AGENTS.md reference: AGENTS.md:L190-L192

Useful? React with 👍 / 👎.

@@ -0,0 +1,5 @@
---
'@moonshot-ai/kimi-code': patch

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 Add changesets for every affected package

This changeset records only @moonshot-ai/kimi-code, although the commit changes source in @moonshot-ai/core and @moonshot-ai/agent-core-v2; the repository's changeset rules require an entry for each changed library, plus entries for user-facing products reached by the change. Without those entries, the release process does not record the actual library changes or the affected desktop/SDK-driven products in their package changelogs.

AGENTS.md reference: AGENTS.md:L184-L188

Useful? React with 👍 / 👎.

Comment thread packages/core/src/llm/policy/policy.ts Outdated
Comment on lines +251 to +252
if (recoveryUsesResolved) {
recoveryRequest = resolvedRequest;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Keep recovery snapshots ahead of media resolution

For requests containing stored kimi-file:// media, an earlier resolver has already set recoveryUsesResolved, so this assignment replaces the intended recovery snapshot with the final request after the media resolver has converted those references to inline or uploaded URLs. createMediaDegradeRecovery consequently records keys for the converted URLs, but its rewrite is later applied to the original request where the keys are still kimi-file://; it matches nothing, and a request_too_large or image-format retry resends the same media instead of degrading it. Clean the snapshot captured by the last resolver that opted into recoveryRequest: 'resolved' rather than assigning the final resolved request here.

Useful? React with 👍 / 👎.

Comment thread packages/core/src/llm/policy/policy.ts Outdated
messages: [...request.content.messages, retryMessage],
},
};
retryMessage = undefined;

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 Retain correction feedback across transient retries

When the first response has invalid tool arguments and the corrective attempt then receives a retryable transport or status error such as a 429, this clears retryMessage before that attempt's outcome is known. The following retry is therefore rebuilt from the original history without the validation feedback, even though no model response consumed it, so the model can repeat the same invalid call. Preserve the correction message across non-model failures and clear or replace it only after receiving another completed model response.

Useful? React with 👍 / 👎.

Comment thread packages/core/src/llm/policy/settle.ts Outdated
Comment on lines +143 to +147
const toolCall = inner.toolCallEnd(event.index);
if (toolCall !== undefined) {
const error = invalidToolArgumentsError(toolCall, request.profile?.tools ?? []);
if (error !== null) {
failure = { error };

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Validate only after the complete tool-call message

For streaming OpenAI-compatible providers, tool_call_end is not a reliable completion boundary: when a gateway omits tool_calls[].index, the decoder emits the call but never emits this event, while interleaved parallel indexes cause the first call to be ended as soon as the second index appears, before its later argument deltas arrive. Because validation occurs only here and an early failure is never reconsidered, the former case still executes malformed arguments and the latter rejects valid calls as truncated. Validate every finalized tool call after message accumulation rather than relying exclusively on decoder boundary events.

AGENTS.md reference: AGENTS.md:L190-L192

Useful? React with 👍 / 👎.

Comment on lines +121 to +123
kind: 'invalid_tool_arguments',
message: `${invalidToolCallText(call.name, result.issue.message)} Generate a new tool call with valid arguments.`,
retryable: 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 Treat schema compilation failures as configuration errors

For an MCP or plugin tool whose JSON schema AJV cannot compile, schemaError turns the compiler failure into an argument issue and this code marks it retryable. No regenerated arguments can satisfy an uncompileable schema, so the default policy wastes every configured attempt asking the model to correct its call, and KIMI_CODE_INFINITE_RETRY can repeat this indefinitely. Surface schema compilation as a deterministic, non-retryable tool-configuration error instead of invalid_tool_arguments.

Useful? React with 👍 / 👎.

@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: 13ea7bbb7e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread packages/core/src/llm/tool-arguments.ts Outdated
}
if (invalid.length === 0) return { messages, invalid };

const invalidIds = new Set(invalid.map(({ call }) => call.id));

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Pair cleanup with the specific reused call occurrence

When resumed or imported history contains sequential completed calls that reuse the same tool-call ID, and only one occurrence has invalid arguments, this global ID set removes every tool result bearing that ID while leaving valid assistant occurrences untouched. The resulting request contains an orphaned valid call that strict providers can reject, so the cleanup intended to recover the session instead leaves it stuck; associate each invalid call with its corresponding result occurrence rather than deleting results globally by ID.

AGENTS.md reference: AGENTS.md:L190-L192

Useful? React with 👍 / 👎.

Comment on lines +329 to +335
const invalidToolArguments = result.error.kind === 'invalid_tool_arguments';
const delayMs = invalidToolArguments
? 0
: (readRetryAfterMs(result.error) ?? retryBackoffDelay(attempt - 1));
const retrying: LlmRunEvent = {
type: 'llm.retrying',
reason: 'backoff',
reason: invalidToolArguments ? 'invalid_tool_arguments' : 'backoff',

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 Account for usage from rejected tool-call attempts

When a provider reports token usage for an invalid-tool-arguments response, this new zero-delay retry path exposes that usage only on llm.retrying and then discards it when the loop continues. Agent-core's retry observer does not record event.usage, its turn projection clears the current attempt on retry, and successful completion records only the final outcome's usage, so up to nine rejected attempts under the default limit disappear from session usage and token accounting. Record each failed attempt's usage before continuing or accumulate it into the completed outcome.

Useful? React with 👍 / 👎.

Comment on lines +241 to +244
const cleaned = cleanToolCallHistory(
resolvedRequest.content.messages,
resolvedRequest.profile?.tools ?? [],
);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Clean history before strict structural projection

When an older history contains an invalid tool-call exchange followed by a normal assistant reply, the strict structure resolver runs while the call and result still separate those assistants; this later cleanup then removes the exchange and appends correction text to the first assistant, leaving two consecutive assistant messages. Because strict recovery has already been consumed and cannot run again, gateways that require alternating roles can reject the repaired request as well, so perform cleanup before structural projection or project the cleaned messages again.

AGENTS.md reference: AGENTS.md:L190-L192

Useful? React with 👍 / 👎.

@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: a32757202f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +323 to +325
if (result.error.kind === 'invalid_tool_arguments') {
if (result.usage !== undefined) {
rejectedUsage = rejectedUsage === undefined ? result.usage : addUsage(rejectedUsage, result.usage);

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 Avoid counting the final rejected attempt twice

When the last permitted attempt returns invalid_tool_arguments with usage, this adds that attempt to rejectedUsage, and the non-retry path then passes the same result to withRejectedUsage, which adds result.usage again. The final failed outcome therefore overstates token usage for the last attempt, affecting session usage and cost accounting; only add an invalid attempt to the accumulator when another attempt will actually run, or exclude the current result when combining totals.

Useful? React with 👍 / 👎.

Comment on lines +211 to +214
content: {
...request.content,
messages: [...request.content.messages, retryMessage],
},

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 Recompute used tokens after appending retry feedback

On an invalid-argument retry, this preserves request.content.usedTokens while appending a new assistant correction message. For Kimi and other model rules whose output cap is computed from usedTokens, a request near the context limit therefore reserves output space as if the correction were absent and can exceed the context window or receive another provider rejection. Recalculate or invalidate usedTokens whenever the retry message is appended.

Useful? React with 👍 / 👎.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant