feat(think): add repairInterruptedToolPart hook for client-resolved tools (#1631)

[threepointone]

Stack

This is PR 3 of 4 for #1631. Stacked; base is fix/chat-recovery-preserve-settled-work (PR #1634). Retargets to main as the stack merges. Diff shown is only this PR's commit.

1. fix(think,ai-chat): make chat-recovery progress signal compaction-immune (#1628) #1633 — progress signal compaction-immune (bug: chat-recovery progress marker is count-based, so compaction can cause premature budget exhaustion #1628) · patch
2. fix(think,ai-chat): preserve settled work when a recovery turn is given up (#1631) #1634 — preserve settled work when a turn is given up · patch
3. ➡️ repairInterruptedToolPart hook (this PR) · minor
4. incident identity + onExhausted payload · minor

This is a public-API addition (a new protected override point) — the one most worth a careful API-shape review. @cloudflare/think only (ai-chat has no transcript-repair pass).

---

Problem (#1631, item 2)

Transcript repair (_repairToolTranscriptParts) flips a tool call with no settled result to an errored tool-result — preserving the record and keeping the provider from 400ing (AI_MissingToolResultsError). That's the right default for server tools.

It's wrong for client-resolved tools like ask_user — a question with no server execute, answered by the user's next message. There, the interrupted call is a question, and the right repair is to preserve it as a text part carrying the prompt, so the model sees a normal Q→A exchange and compaction keeps the question verbatim. Flipping it to output-error turns "the assistant asked X" into "a tool errored" and loses the prose.

Crucially, repair runs and persists before beforeTurn:

// _runInference
const history = await this._repairTranscriptForProvider(this.messages); // repairs + persists + broadcasts
const messages = await convertToModelMessages(truncated, { ... });       // builds model ctx
...
const subclassConfig = (await this.beforeTurn(ctx)) ?? {};               // too late: ctx.messages already built/persisted

So a subclass had no way to shape this for the current turn — any beforeTurn fix-up lands a turn late and races the framework's persisted output-error.

Fix

Extract the per-orphan flip into a protected overridable hook that repair consults during the repair pass (before persist), defaulting to the existing behavior:

/** Repair a single interrupted tool call (no settled result). `input` is already
 *  normalized. Default flips it to an errored tool-result. Override to preserve
 *  client-resolved tools (e.g. ask_user -> a text part carrying the prompt) so the
 *  conversion shapes THIS turn, before repair persists + sends to the model. */
protected repairInterruptedToolPart(
  part: UIMessage["parts"][number]
): UIMessage["parts"][number] {
  return { ...part, state: "output-error", errorText: "The tool call was interrupted before a result was recorded." };
}

_repairToolTranscriptParts now calls this.repairInterruptedToolPart({ ...part, input: normalizedInput }). Default behavior is byte-for-byte unchanged. A subclass returning a text part for ask_user takes effect on the same turn, because it runs inside the repair pass.

Contract (documented on the method): a returned tool part must carry a settled result (so the ignoreIncompleteToolCalls backstop / _incompleteToolCallIds don't drop it); returning a non-tool part (e.g. text) is fine.

Files

• packages/think/src/think.ts — new protected repairInterruptedToolPart; _repairToolTranscriptParts refactored to call it (default unchanged).
• packages/think/src/tests/agents/client-tools.ts — ThinkClientToolsAgent overrides the hook (ask_user → text) to demonstrate the intended usage + a repairToolTranscriptPartsForTest harness.
• packages/think/src/tests/client-tools.test.ts — tests.
• .changeset/think-repair-interrupted-tool-part-hook.md (minor · think).

Tests

• converts an interrupted ask_user into a text part carrying the prompt (the override).
• falls back to the default errored-result repair for non-ask_user tools (default preserved).
• leaves a settled ask_user untouched (only interrupted calls are repaired).

The pre-existing repair tests (message-reconciliation.test.ts: orphan → output-error) still pass — the refactor is behavior-preserving for the default, and the demo override only matches tool-ask_user (other agents' orphans are unaffected).

Verification

• tsc --noEmit clean (think); oxlint clean; oxfmt applied.
• client-tools + message-reconciliation suites: 58 passed. Full think suite: 460 passed.

API review notes

• Name/shape up for discussion: repairInterruptedToolPart(part) -> part. Alternatives considered: a beforeTranscriptRepair(messages) pre-hook (rejected — needs extra persist-gating to avoid the repair's early-return swallowing hook-only changes; per-part is cleaner and persists naturally).
• This only resolves item 2 for think. ai-chat doesn't run this repair pass, so no change there.

Test plan

• CI green
• API-shape sign-off on repairInterruptedToolPart
• Confirm default-path repair unchanged (existing repair tests green)

Made with Cursor

[changeset-bot]

🦋 Changeset detected

Latest commit: fd8a39d

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

This PR includes changesets to release 1 package

Name	Type
@cloudflare/think	Minor

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

[threepointone]

Rebased onto main + docs added

• Rebased onto current main (dropped the now-merged fix(think,ai-chat): make chat-recovery progress signal compaction-immune (#1628) #1633/fix(think,ai-chat): preserve settled work when a recovery turn is given up (#1631) #1634 commits; the diff is just this PR's change). Adapted three test-fixture accesses to the current type graph (the RPC stub return type for repairToolTranscriptPartsForTest stubifies the UIMessage union to never[] at the call site → explicit as UIMessage casts; test-only, production untouched).
• Docs for the new override:
  • docs/think/index.md — new "Repairing interrupted tool calls" subsection (default errored-result + the repairInterruptedToolPart override with the ask_user→text example). Think-only, so not added to chat-agents.md (ai-chat has no transcript-repair pass).
  • packages/think/README.md — brief recovery-section mention with the same example.
  • docs/chat-agents.md — corrected the now-stale { persist: false } recovery-options wording to reflect the merged no-loss default (fix(think,ai-chat): preserve settled work when a recovery turn is given up (#1631) #1634/R1): settled work is never dropped.

Green: think 466, client-tools 50, npm run check clean (91 projects).

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1635

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1635

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1635

hono-agents

npm i https://pkg.pr.new/hono-agents@1635

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1635

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1635

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1635

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1635

commit: fd8a39d