From 4ab9644e1bf27ef757f8722334764fef9a7b32d0 Mon Sep 17 00:00:00 2001
From: Kaiyi <me@kaiyi.cool>
Date: Fri, 3 Jul 2026 13:13:07 +0800
Subject: [PATCH 1/5] feat(agent-core): guide the model away from repeating
 denied or failed tool calls

- system.md: add a diagnose-before-retrying paragraph next to the existing
  permission-denial guidance, covering failed tool calls
- permission: when the user rejects an approval on the main agent, tell the
  model not to re-attempt the exact same call (sub agents already had an
  equivalent hint)
---
 packages/agent-core/src/agent/permission/index.ts |  3 +++
 packages/agent-core/src/profile/default/system.md |  2 ++
 packages/agent-core/test/agent/permission.test.ts | 14 +++++++-------
 3 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/packages/agent-core/src/agent/permission/index.ts b/packages/agent-core/src/agent/permission/index.ts
index 4df71cc90..3d901becf 100644
--- a/packages/agent-core/src/agent/permission/index.ts
+++ b/packages/agent-core/src/agent/permission/index.ts
@@ -302,6 +302,9 @@ export class PermissionManager {
     if (this.agent.type === 'sub') {
       return `${prefix}${suffix} Try a different approach — don't retry the same call, don't attempt to bypass the restriction.`;
     }
+    if (result.decision === 'rejected') {
+      return `${prefix}${suffix} Do not re-attempt the exact same call — think about why it was rejected, then adjust your approach or ask the user what they would prefer.`;
+    }
     return `${prefix}${suffix}`;
   }
 
diff --git a/packages/agent-core/src/profile/default/system.md b/packages/agent-core/src/profile/default/system.md
index 122a29960..f8f56a777 100644
--- a/packages/agent-core/src/profile/default/system.md
+++ b/packages/agent-core/src/profile/default/system.md
@@ -20,6 +20,8 @@ The results of the tool calls will be returned to you in a tool message. You mus
 
 Tool calls run behind the user's permission settings. A rejected or denied call means the user or their policy declined that specific action — adjust your approach, or ask what they would prefer instead. Do not retry the same call unchanged, and do not route around the denial by doing the same thing through a different tool or shell command.
 
+When a tool call fails, diagnose why before acting again: read the error, check your assumptions, and make a focused adjustment. Do not retry the identical call blindly, but do not abandon a viable approach after a single failure either — if you are still stuck after investigating, ask the user.
+
 The system may insert information wrapped in `<system>` tags within user or tool messages. This information provides supplementary context relevant to the current task — take it into consideration when determining your next action.
 
 Tool results and user messages may also include `<system-reminder>` tags. Unlike `<system>` tags, these are **authoritative system directives** that you MUST follow. They bear no direct relation to the specific tool results or user messages in which they appear. Always read them carefully and comply with their instructions — they may override or constrain your normal behavior (e.g., restricting you to read-only actions during plan mode).
diff --git a/packages/agent-core/test/agent/permission.test.ts b/packages/agent-core/test/agent/permission.test.ts
index 3e3a75d6e..5321b26ba 100644
--- a/packages/agent-core/test/agent/permission.test.ts
+++ b/packages/agent-core/test/agent/permission.test.ts
@@ -232,8 +232,8 @@ describe('Agent permission', () => {
       [wire] permission.record_approval_result   { "turnId": 0, "toolCallId": "call_bash", "toolName": "Bash", "action": "Running: printf should-not-run", "result": { "decision": "rejected", "selectedLabel": "reject" }, "time": "<time>" }
       [wire] context.append_loop_event           { "event": { "type": "tool.call", "uuid": "call_bash", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 }, "description": "Running: printf should-not-run", "display": { "kind": "command", "command": "printf should-not-run", "cwd": "<cwd>", "language": "bash" } }, "time": "<time>" }
       [emit] tool.call.started                   { "turnId": 0, "toolCallId": "call_bash", "name": "Bash", "args": { "command": "printf should-not-run", "timeout": 60 }, "description": "Running: printf should-not-run", "display": { "kind": "command", "command": "printf should-not-run", "cwd": "<cwd>", "language": "bash" } }
-      [wire] context.append_loop_event           { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "Tool \\"Bash\\" was not run because the user rejected the approval request.", "isError": true } }, "time": "<time>" }
-      [emit] tool.result                         { "turnId": 0, "toolCallId": "call_bash", "output": "Tool \\"Bash\\" was not run because the user rejected the approval request.", "isError": true }
+      [wire] context.append_loop_event           { "event": { "type": "tool.result", "parentUuid": "call_bash", "toolCallId": "call_bash", "result": { "output": "Tool \\"Bash\\" was not run because the user rejected the approval request. Do not re-attempt the exact same call — think about why it was rejected, then adjust your approach or ask the user what they would prefer.", "isError": true } }, "time": "<time>" }
+      [emit] tool.result                         { "turnId": 0, "toolCallId": "call_bash", "output": "Tool \\"Bash\\" was not run because the user rejected the approval request. Do not re-attempt the exact same call — think about why it was rejected, then adjust your approach or ask the user what they would prefer.", "isError": true }
       [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "usage": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }, "time": "<time>" }
       [emit] turn.step.completed                 { "turnId": 0, "step": 1, "stepId": "<uuid-1>", "usage": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "tool_use" }
       [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 5, "output": 22, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
@@ -242,10 +242,10 @@ describe('Agent permission', () => {
       [emit] turn.step.started                   { "turnId": 0, "step": 2, "stepId": "<uuid-3>" }
       [emit] assistant.delta                     { "turnId": 0, "delta": "I will not run the command." }
       [wire] context.append_loop_event           { "event": { "type": "content.part", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "stepUuid": "<uuid-3>", "part": { "type": "text", "text": "I will not run the command." } }, "time": "<time>" }
-      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 58, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
-      [emit] turn.step.completed                 { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 58, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
-      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 58, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
-      [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 68, "maxContextTokens": 1000000, "contextUsage": 0.000068, "planMode": false, "swarmMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 63, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 63, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 63, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
+      [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-3>", "turnId": "0", "step": 2, "usage": { "inputOther": 93, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }, "time": "<time>" }
+      [emit] turn.step.completed                 { "turnId": 0, "step": 2, "stepId": "<uuid-3>", "usage": { "inputOther": 93, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "finishReason": "end_turn" }
+      [wire] usage.record                        { "model": "mock-model", "usage": { "inputOther": 93, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "usageScope": "turn", "time": "<time>" }
+      [emit] agent.status.updated                { "model": "mock-model", "contextTokens": 103, "maxContextTokens": 1000000, "contextUsage": 0.000103, "planMode": false, "swarmMode": false, "permission": "manual", "usage": { "byModel": { "mock-model": { "inputOther": 98, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } }, "total": { "inputOther": 98, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 }, "currentTurn": { "inputOther": 98, "output": 32, "inputCacheRead": 0, "inputCacheCreation": 0 } } }
       [emit] turn.ended                          { "turnId": 0, "reason": "completed" }
     `);
     expect(execWithEnv).not.toHaveBeenCalled();
@@ -253,7 +253,7 @@ describe('Agent permission', () => {
       messages:
         <last>
         assistant: text "I will try Bash."  calls call_bash:Bash { "command": "printf should-not-run", "timeout": 60 }
-        tool[call_bash]: text "<system>ERROR: Tool execution failed.</system>\\nTool \\"Bash\\" was not run because the user rejected the approval request."
+        tool[call_bash]: text "<system>ERROR: Tool execution failed.</system>\\nTool \\"Bash\\" was not run because the user rejected the approval request. Do not re-attempt the exact same call — think about why it was rejected, then adjust your approach or ask the user what they would prefer."
     `);
     await ctx.expectResumeMatches();
   });

From c8633ca62da642eb9bf4d505cf0b7a658c257488 Mon Sep 17 00:00:00 2001
From: Kaiyi <me@kaiyi.cool>
Date: Fri, 3 Jul 2026 13:13:23 +0800
Subject: [PATCH 2/5] fix(agent-core): close abandoned tool exchanges and
 dedupe duplicate tool_use ids

A turn that dies between a recorded tool.call and its paired tool.result
(e.g. a transcript write failure mid-batch) used to leave
pendingToolResultIds open forever: every later message was stranded in
deferredMessages and user input was silently swallowed.

- runOneTurn now defensively closes any dangling tool calls when a turn
  ends (completed, cancelled, or failed), synthesizing an error result
  that names the cause, with a warn log and a tool_exchange_abandoned
  telemetry event
- the projector drops assistant tool calls whose id already appeared
  earlier (first occurrence wins): a duplicate id is wire-invalid on
  strict providers and not repairable by the strict resend; reported via
  the existing projection-repair log and telemetry
- resume-side closePendingToolResults now logs what it closes (warn for
  a mid-history gap, info for the routine trailing interruption)
---
 .../agent-core/src/agent/context/index.ts     | 49 +++++++++++--
 .../agent-core/src/agent/context/projector.ts | 44 +++++++++++-
 packages/agent-core/src/agent/turn/index.ts   | 42 ++++++++++++
 .../test/agent/context/projector.test.ts      | 55 +++++++++++++++
 packages/agent-core/test/agent/turn.test.ts   | 68 ++++++++++++++++++-
 5 files changed, 250 insertions(+), 8 deletions(-)

diff --git a/packages/agent-core/src/agent/context/index.ts b/packages/agent-core/src/agent/context/index.ts
index 3b3580187..a49f52ebc 100644
--- a/packages/agent-core/src/agent/context/index.ts
+++ b/packages/agent-core/src/agent/context/index.ts
@@ -397,6 +397,7 @@ export class ContextMemory {
     let reordered = 0;
     let synthesized = 0;
     let droppedOrphan = 0;
+    let duplicateDropped = 0;
     let leadingDropped = 0;
     let assistantsMerged = 0;
     let whitespaceDropped = 0;
@@ -404,6 +405,7 @@ export class ContextMemory {
       if (anomaly.kind === 'tool_result_reordered') reordered += 1;
       else if (anomaly.kind === 'tool_result_synthesized') synthesized += 1;
       else if (anomaly.kind === 'orphan_tool_result_dropped') droppedOrphan += 1;
+      else if (anomaly.kind === 'duplicate_tool_call_dropped') duplicateDropped += 1;
       else if (anomaly.kind === 'leading_non_user_dropped') leadingDropped += 1;
       else if (anomaly.kind === 'consecutive_assistants_merged') assistantsMerged += 1;
       else whitespaceDropped += 1;
@@ -417,6 +419,7 @@ export class ContextMemory {
       reordered,
       synthesized,
       droppedOrphan,
+      duplicateDropped,
       leadingDropped,
       assistantsMerged,
       whitespaceDropped,
@@ -426,6 +429,7 @@ export class ContextMemory {
       reordered,
       synthesized,
       dropped_orphan: droppedOrphan,
+      duplicate_dropped: duplicateDropped,
       leading_dropped: leadingDropped,
       assistants_merged: assistantsMerged,
       whitespace_dropped: whitespaceDropped,
@@ -464,7 +468,15 @@ export class ContextMemory {
 
   finishResume(): void {
     this.openSteps.clear();
-    this.closePendingToolResults();
+    const closed = this.closePendingToolResults();
+    if (closed.length > 0) {
+      // Routine end-of-resume close of a genuinely interrupted trailing call
+      // (e.g. the process died mid-tool), logged for traceability.
+      this.agent.log.info('closed interrupted tool calls at end of resume', {
+        closed: closed.length,
+        toolCallIds: closed.slice(0, 5),
+      });
+    }
   }
 
   // Synthesize interrupted tool results for any still-open tool calls, closing
@@ -473,9 +485,11 @@ export class ContextMemory {
   // exactly where it occurred — otherwise it would keep `hasOpenToolExchange`
   // true and strand every later message in `deferredMessages`, so only the
   // trailing exchange ends up aligned. `finishResume` runs the same routine once
-  // more to close a genuine trailing interruption at end of resume.
-  private closePendingToolResults(): void {
-    if (this.pendingToolResultIds.size === 0) return;
+  // more to close a genuine trailing interruption at end of resume, and
+  // `closeAbandonedToolExchange` reuses it (with a live-turn message) as the
+  // turn-end teardown. Returns the ids it closed; callers own the logging.
+  private closePendingToolResults(output: string = TOOL_INTERRUPTED_ON_RESUME_OUTPUT): string[] {
+    if (this.pendingToolResultIds.size === 0) return [];
     const interruptedToolCallIds = [...this.pendingToolResultIds];
     for (const toolCallId of interruptedToolCallIds) {
       this.appendLoopEvent({
@@ -483,11 +497,25 @@ export class ContextMemory {
         parentUuid: toolCallId,
         toolCallId,
         result: {
-          output: TOOL_INTERRUPTED_ON_RESUME_OUTPUT,
+          output,
           isError: true,
         },
       });
     }
+    return interruptedToolCallIds;
+  }
+
+  /**
+   * Defensive teardown for a live turn that ended — normally, cancelled, or
+   * failed — while recorded tool calls were still awaiting results (e.g. the
+   * batch's result dispatch died after a `tool.call` was already recorded).
+   * Synthesizes an error result for each dangling call so the exchange closes:
+   * left open, it would keep `hasOpenToolExchange` true and strand every later
+   * message in `deferredMessages`, silently swallowing user input. No-op when
+   * the exchange is already closed. Returns the number of calls it closed.
+   */
+  closeAbandonedToolExchange(output: string): number {
+    return this.closePendingToolResults(output).length;
   }
 
   appendLoopEvent(event: LoopRecordedEvent): void {
@@ -501,7 +529,16 @@ export class ContextMemory {
         // earlier step were interrupted (the invariant guarantees this never
         // happens live, so this is a no-op outside replay). Close them in place
         // before opening the new step so mid-history gaps stay aligned.
-        this.closePendingToolResults();
+        const closed = this.closePendingToolResults();
+        if (closed.length > 0) {
+          // A mid-history gap means results were lost before this boundary —
+          // a genuine defect worth investigating, unlike the expected trailing
+          // interruption `finishResume` closes.
+          this.agent.log.warn('closed unresolved tool calls at a step boundary', {
+            closed: closed.length,
+            toolCallIds: closed.slice(0, 5),
+          });
+        }
         const message: ContextMessage = {
           role: 'assistant',
           content: [],
diff --git a/packages/agent-core/src/agent/context/projector.ts b/packages/agent-core/src/agent/context/projector.ts
index ebf08dc1b..7d49c4098 100644
--- a/packages/agent-core/src/agent/context/projector.ts
+++ b/packages/agent-core/src/agent/context/projector.ts
@@ -73,6 +73,8 @@ export type ProjectionAnomaly =
   | { readonly kind: 'tool_result_synthesized'; readonly toolCallId: string; readonly trailing: boolean }
   /** A result with no matching call anywhere was dropped (wire exits only). */
   | { readonly kind: 'orphan_tool_result_dropped'; readonly toolCallId: string }
+  /** A tool call whose id already appeared earlier was dropped (always). */
+  | { readonly kind: 'duplicate_tool_call_dropped'; readonly toolCallId: string }
   /** A leading non-user message was dropped so the first turn is user (strict). */
   | { readonly kind: 'leading_non_user_dropped'; readonly role: string }
   /** Two adjacent assistant turns were merged into one (strict). */
@@ -82,7 +84,10 @@ export type ProjectionAnomaly =
 
 export function project(history: readonly ContextMessage[], options?: ProjectOptions): Message[] {
   let result = repairToolExchangeAdjacency(
-    mergeAdjacentUserMessages(history, options?.onAnomaly),
+    dedupeDuplicateToolCalls(
+      mergeAdjacentUserMessages(history, options?.onAnomaly),
+      options?.onAnomaly,
+    ),
     options,
   );
   if (options?.mergeConsecutiveAssistants === true) {
@@ -189,6 +194,43 @@ function repairToolExchangeAdjacency(
   return out;
 }
 
+// Strict providers reject a request whose assistant messages carry two
+// `tool_use` blocks with the same id ("tool_use ids must be unique"), and the
+// context state machine only ever records one result per id — so a duplicate
+// emitted by a (buggy) provider would strand the session behind a 400 that even
+// the strict resend cannot repair. Keep the first occurrence, drop the rest,
+// and drop an assistant message entirely when duplicates were all it carried.
+// Runs on every projection, before the adjacency repair, so pending-result
+// matching never sees the duplicate.
+function dedupeDuplicateToolCalls(
+  messages: readonly Message[],
+  onAnomaly?: (anomaly: ProjectionAnomaly) => void,
+): Message[] {
+  const seenToolCallIds = new Set<string>();
+  const out: Message[] = [];
+  for (const message of messages) {
+    if (message.role !== 'assistant' || message.toolCalls.length === 0) {
+      out.push(message);
+      continue;
+    }
+    const kept = message.toolCalls.filter((toolCall) => {
+      if (seenToolCallIds.has(toolCall.id)) {
+        onAnomaly?.({ kind: 'duplicate_tool_call_dropped', toolCallId: toolCall.id });
+        return false;
+      }
+      seenToolCallIds.add(toolCall.id);
+      return true;
+    });
+    if (kept.length === message.toolCalls.length) {
+      out.push(message);
+      continue;
+    }
+    if (kept.length === 0 && message.content.length === 0) continue;
+    out.push({ ...message, toolCalls: kept });
+  }
+  return out;
+}
+
 // Remove any `tool_result` whose `toolCallId` matches no assistant `tool_use`
 // anywhere in the projected messages. Strict providers reject such a stray
 // result, and it is useless to the model regardless (it has no record of the
diff --git a/packages/agent-core/src/agent/turn/index.ts b/packages/agent-core/src/agent/turn/index.ts
index 847794aaa..b79b6f83b 100644
--- a/packages/agent-core/src/agent/turn/index.ts
+++ b/packages/agent-core/src/agent/turn/index.ts
@@ -552,6 +552,11 @@ export class TurnFlow {
         }
       }
     }
+    // A live turn must never end with recorded tool calls still awaiting
+    // results; if one does (a dispatch failure mid-batch broke the "every
+    // recorded call gets a result" invariant), close the exchange now so the
+    // context state machine cannot strand later messages in deferredMessages.
+    this.closeAbandonedToolExchange(ended);
     // Emit the terminal turn.ended and (for a standalone turn) release the active
     // turn in the SAME synchronous frame, so the session is observably idle the
     // instant turn.ended fires. A goal drive keeps the active turn across its
@@ -840,6 +845,29 @@ export class TurnFlow {
     }
   }
 
+  // Guarded so this repair can never turn a finished turn into a crash: a
+  // failure to close (e.g. record persistence still broken) is logged and the
+  // projection-level safeguards remain the last line of defense.
+  private closeAbandonedToolExchange(ended: TurnEndedEvent): void {
+    try {
+      const closed = this.agent.context.closeAbandonedToolExchange(
+        abandonedToolResultOutput(ended),
+      );
+      if (closed === 0) return;
+      this.agent.log.warn('closed abandoned tool exchange at turn end', {
+        turnId: ended.turnId,
+        reason: ended.reason,
+        closed,
+      });
+      this.agent.telemetry.track('tool_exchange_abandoned', {
+        reason: ended.reason,
+        closed,
+      });
+    } catch (error) {
+      this.agent.log.warn('failed to close abandoned tool exchange', { error });
+    }
+  }
+
   private buildDispatchEvent(turnId: number) {
     return createLoopEventDispatcher({
       appendTranscriptRecord: async (event: LoopRecordedEvent) => {
@@ -1265,3 +1293,17 @@ function telemetryToolErrorType(result: ToolTelemetryResult): string {
 function toolResultText(result: ToolTelemetryResult): string {
   return toolOutputText(result.output);
 }
+
+// Output for a tool call abandoned by its turn (see closeAbandonedToolExchange):
+// name the cause so the model treats the gap as an interruption to reason about,
+// not a tool outcome. Mirrors the phrasing of the resume-time synthesis in
+// `ContextMemory`.
+function abandonedToolResultOutput(ended: TurnEndedEvent): string {
+  const cause =
+    ended.reason === 'cancelled'
+      ? 'the turn was cancelled'
+      : ended.reason === 'failed'
+        ? `the turn failed${ended.error !== undefined ? ` (${ended.error.message})` : ''}`
+        : 'the turn ended';
+  return `Tool call did not complete: ${cause} before its result was recorded. Do not assume the tool completed successfully.`;
+}
diff --git a/packages/agent-core/test/agent/context/projector.test.ts b/packages/agent-core/test/agent/context/projector.test.ts
index f3cfbcf51..fdbd80dca 100644
--- a/packages/agent-core/test/agent/context/projector.test.ts
+++ b/packages/agent-core/test/agent/context/projector.test.ts
@@ -543,6 +543,61 @@ describe('project strict-provider sanitizers', () => {
   });
 });
 
+describe('project duplicate tool_use ids', () => {
+  // A provider that (buggily) emits two tool_use blocks with the same id
+  // produces a wire-invalid request on every strict provider ("tool_use ids
+  // must be unique"), and the state machine only ever records one result for
+  // the id — so without projection-time dedup the session is stuck behind a
+  // 400 that even the strict resend cannot repair.
+  it('drops a duplicate tool call id within one assistant message', () => {
+    const anomalies: ProjectionAnomaly[] = [];
+    const projected = project(
+      [
+        user('u1'),
+        assistant(['call_dup', 'call_dup'], 'calling twice'),
+        tool('call_dup', 'result'),
+        user('u2'),
+      ],
+      { dropOrphanResults: true, onAnomaly: (anomaly) => anomalies.push(anomaly) },
+    );
+    const assistantMessage = projected.find((message) => message.role === 'assistant');
+    expect(assistantMessage?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_dup']);
+    expect(anomalies).toContainEqual({
+      kind: 'duplicate_tool_call_dropped',
+      toolCallId: 'call_dup',
+    });
+    expect(everyToolUseImmediatelyAnswered(projected)).toBe(true);
+  });
+
+  it('drops a tool call id repeated across assistant messages, keeping the first', () => {
+    const projected = project(
+      [
+        user('u1'),
+        assistant(['call_a'], 'first'),
+        tool('call_a'),
+        assistant(['call_a', 'call_b'], 'second'),
+        tool('call_b'),
+        user('u2'),
+      ],
+      { dropOrphanResults: true },
+    );
+    const assistants = projected.filter(
+      (message) => message.role === 'assistant' && message.toolCalls.length > 0,
+    );
+    expect(assistants[0]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_a']);
+    expect(assistants[1]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_b']);
+    expect(everyToolUseImmediatelyAnswered(projected)).toBe(true);
+  });
+
+  it('drops an assistant message left empty after removing duplicate tool calls', () => {
+    const projected = project(
+      [user('u1'), assistant(['call_a'], 'first'), tool('call_a'), assistant(['call_a']), user('u2')],
+      { dropOrphanResults: true },
+    );
+    expect(projected.map((message) => message.role)).toEqual(['user', 'assistant', 'tool', 'user']);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Property-based fuzz test
 // ---------------------------------------------------------------------------
diff --git a/packages/agent-core/test/agent/turn.test.ts b/packages/agent-core/test/agent/turn.test.ts
index e47eefa04..d1e450375 100644
--- a/packages/agent-core/test/agent/turn.test.ts
+++ b/packages/agent-core/test/agent/turn.test.ts
@@ -17,7 +17,8 @@ import { describe, expect, it, vi } from 'vitest';
 
 import { HookEngine } from '../../src/session/hooks';
 import { abortError } from '../../src/utils/abort';
-import type { AgentOptions } from '../../src/agent';
+import type { AgentOptions, AgentRecord, AgentRecordPersistence } from '../../src/agent';
+import { InMemoryAgentRecordPersistence } from '../../src/agent/records';
 import { ErrorCodes, KimiError } from '../../src/errors';
 import type { Logger, LogPayload } from '../../src/logging';
 import type {
@@ -1928,3 +1929,68 @@ function textResult(text: string): Awaited<ReturnType<GenerateFn>> {
     rawFinishReason: 'stop',
   };
 }
+
+describe('abandoned tool exchange teardown', () => {
+  it('closes dangling tool calls when a turn dies mid-batch so follow-up messages are not swallowed', async () => {
+    // A transcript write failure between a recorded tool.call and its paired
+    // tool.result breaks the batch's "every recorded call gets a result"
+    // invariant: the result-dispatch loop dies, the turn fails, and
+    // pendingToolResultIds stays open — stranding every later message in
+    // deferredMessages.
+    const base = new InMemoryAgentRecordPersistence();
+    let failedOnce = false;
+    const persistence: AgentRecordPersistence = {
+      read: () => base.read(),
+      append: (record: AgentRecord) => {
+        if (
+          !failedOnce &&
+          record.type === 'context.append_loop_event' &&
+          record.event.type === 'tool.result'
+        ) {
+          failedOnce = true;
+          throw new Error('transcript write failed');
+        }
+        base.append(record);
+      },
+      rewrite: (records) => {
+        base.rewrite(records);
+      },
+      flush: () => base.flush(),
+      close: () => base.close(),
+    };
+    const ctx = testAgent({ kaos: createCommandKaos('ok'), persistence });
+    ctx.configure({ tools: ['Bash'] });
+    await ctx.rpc.setPermission({ mode: 'auto' });
+
+    ctx.mockNextResponse(
+      { type: 'text', text: 'I will run both commands.' },
+      bashCallWithId('call_one', 'echo one'),
+      bashCallWithId('call_two', 'echo two'),
+    );
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'run both' }] });
+    const events = await ctx.untilTurnEnd();
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        event: 'turn.ended',
+        args: expect.objectContaining({ reason: 'failed' }),
+      }),
+    );
+
+    // Every recorded tool.call must still get a result: the turn teardown
+    // synthesizes an error result for each dangling call.
+    const toolMessages = ctx.agent.context.history.filter((message) => message.role === 'tool');
+    expect(toolMessages.map((message) => message.toolCallId)).toEqual(['call_one', 'call_two']);
+    for (const message of toolMessages) {
+      expect(message.isError).toBe(true);
+    }
+
+    // With the exchange closed, a follow-up message reaches the history instead
+    // of being stranded in deferredMessages forever.
+    ctx.agent.context.appendMessage({
+      role: 'user',
+      content: [{ type: 'text', text: 'follow-up after failure' }],
+      toolCalls: [],
+    });
+    expect(JSON.stringify(ctx.agent.context.history)).toContain('follow-up after failure');
+  });
+});

From 5316887bad69e542eb0a07eb6e18c99fb29bba07 Mon Sep 17 00:00:00 2001
From: Kaiyi <me@kaiyi.cool>
Date: Fri, 3 Jul 2026 13:26:58 +0800
Subject: [PATCH 3/5] chore: add changesets for tool exchange fixes

---
 .changeset/close-abandoned-tool-exchanges.md | 5 +++++
 .changeset/dedupe-duplicate-tool-call-ids.md | 5 +++++
 2 files changed, 10 insertions(+)
 create mode 100644 .changeset/close-abandoned-tool-exchanges.md
 create mode 100644 .changeset/dedupe-duplicate-tool-call-ids.md

diff --git a/.changeset/close-abandoned-tool-exchanges.md b/.changeset/close-abandoned-tool-exchanges.md
new file mode 100644
index 000000000..94f397435
--- /dev/null
+++ b/.changeset/close-abandoned-tool-exchanges.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix sessions silently dropping later user messages after a turn was interrupted between a tool call and its result.
diff --git a/.changeset/dedupe-duplicate-tool-call-ids.md b/.changeset/dedupe-duplicate-tool-call-ids.md
new file mode 100644
index 000000000..ab358a693
--- /dev/null
+++ b/.changeset/dedupe-duplicate-tool-call-ids.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix requests being rejected by strict providers when the model emits duplicate tool call ids.

From 7335d49de412d8f36405994abe9e23c5bbed27e2 Mon Sep 17 00:00:00 2001
From: Kaiyi <me@kaiyi.cool>
Date: Fri, 3 Jul 2026 14:06:24 +0800
Subject: [PATCH 4/5] fix(agent-core): scope duplicate tool_use id dedup to the
 strict resend

Unconditional dedup regressed providers that emit per-response counter
ids (e.g. call_0 in every step) and accept their own duplicates: later
tool exchanges silently vanished from the projected history, and a
duplicate call's own recorded result was left dangling.

- the dedupe pass is now opt-in via dedupeDuplicateToolCalls and enabled
  only in strictMessages, so the normal projection keeps the history the
  provider produced
- the pass also drops every tool result after the first for an id, so no
  dangling tool message survives; when the kept call has no result of
  its own, the surviving one is reattached by the adjacency repair
- kosong now classifies the Anthropic "tool_use ids must be unique" 400
  as a recoverable request-structure error so it triggers the strict
  resend
---
 .../agent-core/src/agent/context/index.ts     | 24 +++--
 .../agent-core/src/agent/context/projector.ts | 80 ++++++++++------
 .../agent-core/test/agent/context.test.ts     | 60 ++++++++++++
 .../test/agent/context/projector.test.ts      | 94 ++++++++++++++-----
 packages/kosong/src/errors.ts                 |  5 +
 packages/kosong/test/errors.test.ts           |  8 ++
 6 files changed, 209 insertions(+), 62 deletions(-)

diff --git a/packages/agent-core/src/agent/context/index.ts b/packages/agent-core/src/agent/context/index.ts
index a49f52ebc..5c93ebf45 100644
--- a/packages/agent-core/src/agent/context/index.ts
+++ b/packages/agent-core/src/agent/context/index.ts
@@ -397,7 +397,8 @@ export class ContextMemory {
     let reordered = 0;
     let synthesized = 0;
     let droppedOrphan = 0;
-    let duplicateDropped = 0;
+    let duplicateCallsDropped = 0;
+    let duplicateResultsDropped = 0;
     let leadingDropped = 0;
     let assistantsMerged = 0;
     let whitespaceDropped = 0;
@@ -405,7 +406,8 @@ export class ContextMemory {
       if (anomaly.kind === 'tool_result_reordered') reordered += 1;
       else if (anomaly.kind === 'tool_result_synthesized') synthesized += 1;
       else if (anomaly.kind === 'orphan_tool_result_dropped') droppedOrphan += 1;
-      else if (anomaly.kind === 'duplicate_tool_call_dropped') duplicateDropped += 1;
+      else if (anomaly.kind === 'duplicate_tool_call_dropped') duplicateCallsDropped += 1;
+      else if (anomaly.kind === 'duplicate_tool_result_dropped') duplicateResultsDropped += 1;
       else if (anomaly.kind === 'leading_non_user_dropped') leadingDropped += 1;
       else if (anomaly.kind === 'consecutive_assistants_merged') assistantsMerged += 1;
       else whitespaceDropped += 1;
@@ -419,7 +421,8 @@ export class ContextMemory {
       reordered,
       synthesized,
       droppedOrphan,
-      duplicateDropped,
+      duplicateCallsDropped,
+      duplicateResultsDropped,
       leadingDropped,
       assistantsMerged,
       whitespaceDropped,
@@ -429,7 +432,8 @@ export class ContextMemory {
       reordered,
       synthesized,
       dropped_orphan: droppedOrphan,
-      duplicate_dropped: duplicateDropped,
+      duplicate_calls_dropped: duplicateCallsDropped,
+      duplicate_results_dropped: duplicateResultsDropped,
       leading_dropped: leadingDropped,
       assistants_merged: assistantsMerged,
       whitespace_dropped: whitespaceDropped,
@@ -447,15 +451,17 @@ export class ContextMemory {
   }
 
   // Last-resort projection for the post-400 strict resend: close every open tool
-  // call (including a trailing in-flight one), drop stray tool results, drop a
-  // leading non-user message, and merge consecutive assistant turns, so the
-  // request is wire-compliant for strict providers no matter how the history was
-  // mangled. Only used when the provider has already rejected the normal
-  // projection — see the adjacency fallback in `turn-step`.
+  // call (including a trailing in-flight one), drop stray tool results, dedupe
+  // duplicate tool call ids (with their extra results), drop a leading non-user
+  // message, and merge consecutive assistant turns, so the request is
+  // wire-compliant for strict providers no matter how the history was mangled.
+  // Only used when the provider has already rejected the normal projection —
+  // see the adjacency fallback in `turn-step`.
   get strictMessages(): Message[] {
     return this.project(this.history, {
       synthesizeMissing: true,
       dropOrphanResults: true,
+      dedupeDuplicateToolCalls: true,
       dropLeadingNonUser: true,
       mergeConsecutiveAssistants: true,
     });
diff --git a/packages/agent-core/src/agent/context/projector.ts b/packages/agent-core/src/agent/context/projector.ts
index 7d49c4098..75ee0fbcb 100644
--- a/packages/agent-core/src/agent/context/projector.ts
+++ b/packages/agent-core/src/agent/context/projector.ts
@@ -44,6 +44,18 @@ export interface ProjectOptions {
    * consecutive assistant turns do not arise in well-formed transcripts.
    */
   readonly mergeConsecutiveAssistants?: boolean;
+  /**
+   * When `true`, drop assistant tool calls whose id already appeared earlier
+   * (first occurrence wins; a message left with no content and no calls is
+   * dropped), and drop every tool result after the first for a given id so the
+   * kept call keeps exactly one answer. Duplicate ids are wire-invalid on
+   * strict providers ("`tool_use` ids must be unique") and no other pass can
+   * repair them. Strict-resend only: a provider that accepted the duplicates
+   * when it produced them (e.g. per-response counter ids like `call_0`) must
+   * keep seeing the history it generated — deduping the normal path would
+   * silently erase its later tool exchanges.
+   */
+  readonly dedupeDuplicateToolCalls?: boolean;
   /**
    * Optional sink invoked for every repair the projector applies to keep the
    * outgoing wire valid: a displaced result moved back next to its call, a
@@ -73,8 +85,10 @@ export type ProjectionAnomaly =
   | { readonly kind: 'tool_result_synthesized'; readonly toolCallId: string; readonly trailing: boolean }
   /** A result with no matching call anywhere was dropped (wire exits only). */
   | { readonly kind: 'orphan_tool_result_dropped'; readonly toolCallId: string }
-  /** A tool call whose id already appeared earlier was dropped (always). */
+  /** A tool call whose id already appeared earlier was dropped (strict-resend only). */
   | { readonly kind: 'duplicate_tool_call_dropped'; readonly toolCallId: string }
+  /** A second result for an already-answered id was dropped (strict-resend only). */
+  | { readonly kind: 'duplicate_tool_result_dropped'; readonly toolCallId: string }
   /** A leading non-user message was dropped so the first turn is user (strict). */
   | { readonly kind: 'leading_non_user_dropped'; readonly role: string }
   /** Two adjacent assistant turns were merged into one (strict). */
@@ -83,13 +97,11 @@ export type ProjectionAnomaly =
   | { readonly kind: 'whitespace_text_dropped'; readonly role: string };
 
 export function project(history: readonly ContextMessage[], options?: ProjectOptions): Message[] {
-  let result = repairToolExchangeAdjacency(
-    dedupeDuplicateToolCalls(
-      mergeAdjacentUserMessages(history, options?.onAnomaly),
-      options?.onAnomaly,
-    ),
-    options,
-  );
+  let result = mergeAdjacentUserMessages(history, options?.onAnomaly);
+  if (options?.dedupeDuplicateToolCalls === true) {
+    result = dedupeDuplicateToolCalls(result, options.onAnomaly);
+  }
+  result = repairToolExchangeAdjacency(result, options);
   if (options?.mergeConsecutiveAssistants === true) {
     result = mergeConsecutiveAssistantMessages(result, options.onAnomaly);
   }
@@ -195,38 +207,48 @@ function repairToolExchangeAdjacency(
 }
 
 // Strict providers reject a request whose assistant messages carry two
-// `tool_use` blocks with the same id ("tool_use ids must be unique"), and the
-// context state machine only ever records one result per id — so a duplicate
-// emitted by a (buggy) provider would strand the session behind a 400 that even
-// the strict resend cannot repair. Keep the first occurrence, drop the rest,
-// and drop an assistant message entirely when duplicates were all it carried.
-// Runs on every projection, before the adjacency repair, so pending-result
-// matching never sees the duplicate.
+// `tool_use` blocks with the same id ("tool_use ids must be unique"). Keep the
+// first occurrence of each call id, drop the rest, and drop an assistant
+// message entirely when duplicates were all it carried. Every result after the
+// first for a given id is dropped with its call, so no dangling tool message
+// survives the dedupe; when the kept call has no result of its own, the later
+// duplicate's surviving result is reattached by the adjacency repair. Runs
+// before the adjacency repair so pending-result matching never sees the
+// duplicate. Strict-resend only (see `ProjectOptions.dedupeDuplicateToolCalls`):
+// the normal projection keeps duplicates verbatim for the lax provider that
+// produced and accepts them.
 function dedupeDuplicateToolCalls(
   messages: readonly Message[],
   onAnomaly?: (anomaly: ProjectionAnomaly) => void,
 ): Message[] {
   const seenToolCallIds = new Set<string>();
+  const seenToolResultIds = new Set<string>();
   const out: Message[] = [];
   for (const message of messages) {
-    if (message.role !== 'assistant' || message.toolCalls.length === 0) {
-      out.push(message);
+    if (message.role === 'assistant' && message.toolCalls.length > 0) {
+      const kept = message.toolCalls.filter((toolCall) => {
+        if (seenToolCallIds.has(toolCall.id)) {
+          onAnomaly?.({ kind: 'duplicate_tool_call_dropped', toolCallId: toolCall.id });
+          return false;
+        }
+        seenToolCallIds.add(toolCall.id);
+        return true;
+      });
+      if (kept.length === message.toolCalls.length) {
+        out.push(message);
+      } else if (kept.length > 0 || message.content.length > 0) {
+        out.push({ ...message, toolCalls: kept });
+      }
       continue;
     }
-    const kept = message.toolCalls.filter((toolCall) => {
-      if (seenToolCallIds.has(toolCall.id)) {
-        onAnomaly?.({ kind: 'duplicate_tool_call_dropped', toolCallId: toolCall.id });
-        return false;
+    if (message.role === 'tool' && message.toolCallId !== undefined) {
+      if (seenToolResultIds.has(message.toolCallId)) {
+        onAnomaly?.({ kind: 'duplicate_tool_result_dropped', toolCallId: message.toolCallId });
+        continue;
       }
-      seenToolCallIds.add(toolCall.id);
-      return true;
-    });
-    if (kept.length === message.toolCalls.length) {
-      out.push(message);
-      continue;
+      seenToolResultIds.add(message.toolCallId);
     }
-    if (kept.length === 0 && message.content.length === 0) continue;
-    out.push({ ...message, toolCalls: kept });
+    out.push(message);
   }
   return out;
 }
diff --git a/packages/agent-core/test/agent/context.test.ts b/packages/agent-core/test/agent/context.test.ts
index 2d3d15e88..4b613dde0 100644
--- a/packages/agent-core/test/agent/context.test.ts
+++ b/packages/agent-core/test/agent/context.test.ts
@@ -1254,3 +1254,63 @@ function textOf(message: Message): string {
     .map((part) => part.text)
     .join('');
 }
+
+describe('strictMessages duplicate tool call ids', () => {
+  it('keeps duplicates on the normal projection but dedupes them in the strict one', () => {
+    const ctx = testAgent();
+    ctx.configure();
+    ctx.agent.context.appendUserMessage([{ type: 'text', text: 'run the tool twice' }]);
+    // A provider with per-response counter ids reuses `call_dup` in two steps;
+    // both exchanges record their own result.
+    for (const step of [1, 2]) {
+      const stepUuid = `dup-step-${String(step)}`;
+      ctx.dispatch({
+        type: 'context.append_loop_event',
+        event: { type: 'step.begin', uuid: stepUuid, turnId: '', step },
+      });
+      ctx.dispatch({
+        type: 'context.append_loop_event',
+        event: {
+          type: 'tool.call',
+          uuid: `dup-call-${String(step)}`,
+          turnId: '',
+          step,
+          stepUuid,
+          toolCallId: 'call_dup',
+          name: 'Run',
+          args: { attempt: step },
+        },
+      });
+      ctx.dispatch({
+        type: 'context.append_loop_event',
+        event: { type: 'step.end', uuid: stepUuid, turnId: '', step },
+      });
+      ctx.dispatch({
+        type: 'context.append_loop_event',
+        event: {
+          type: 'tool.result',
+          parentUuid: `dup-call-${String(step)}`,
+          toolCallId: 'call_dup',
+          result: { output: `result ${String(step)}` },
+        },
+      });
+    }
+
+    // Normal projection: the lax provider that produced the duplicate ids
+    // accepts them, so nothing is dropped.
+    const normal = ctx.agent.context.messages;
+    expect(
+      normal.filter((message) => message.role === 'assistant').flatMap((m) => m.toolCalls),
+    ).toHaveLength(2);
+    expect(normal.filter((message) => message.role === 'tool')).toHaveLength(2);
+
+    // Strict resend projection: one call, one result.
+    const strict = ctx.agent.context.strictMessages;
+    expect(
+      strict.filter((message) => message.role === 'assistant').flatMap((m) => m.toolCalls),
+    ).toHaveLength(1);
+    const strictResults = strict.filter((message) => message.role === 'tool');
+    expect(strictResults).toHaveLength(1);
+    expect(textOf(strictResults[0]!)).toBe('result 1');
+  });
+});
diff --git a/packages/agent-core/test/agent/context/projector.test.ts b/packages/agent-core/test/agent/context/projector.test.ts
index fdbd80dca..3742880e7 100644
--- a/packages/agent-core/test/agent/context/projector.test.ts
+++ b/packages/agent-core/test/agent/context/projector.test.ts
@@ -544,13 +544,61 @@ describe('project strict-provider sanitizers', () => {
 });
 
 describe('project duplicate tool_use ids', () => {
-  // A provider that (buggily) emits two tool_use blocks with the same id
-  // produces a wire-invalid request on every strict provider ("tool_use ids
-  // must be unique"), and the state machine only ever records one result for
-  // the id — so without projection-time dedup the session is stuck behind a
-  // 400 that even the strict resend cannot repair.
-  it('drops a duplicate tool call id within one assistant message', () => {
+  // A provider that (buggily, or via per-response counter ids like `call_0`)
+  // emits two tool_use blocks with the same id produces a request strict
+  // providers reject ("`tool_use` ids must be unique"). The normal projection
+  // must leave the duplicates untouched — the lax provider that produced them
+  // accepts them, and deduping would silently erase its later tool exchanges.
+  // Only the strict resend (after a provider already rejected the request)
+  // dedupes, dropping later duplicate calls together with their recorded
+  // results so no dangling tool message survives.
+  const duplicateAcrossSteps: ContextMessage[] = [
+    user('u1'),
+    assistant(['call_a'], 'first'),
+    tool('call_a', 'first result'),
+    assistant(['call_a', 'call_b'], 'second'),
+    tool('call_a', 'second result'),
+    tool('call_b'),
+    user('u2'),
+  ];
+
+  it('leaves duplicate ids and their results untouched on the normal path', () => {
+    const projected = project(duplicateAcrossSteps, { dropOrphanResults: true });
+    const assistants = projected.filter(
+      (message) => message.role === 'assistant' && message.toolCalls.length > 0,
+    );
+    expect(assistants[0]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_a']);
+    expect(assistants[1]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_a', 'call_b']);
+    expect(projected.filter((message) => message.role === 'tool')).toHaveLength(3);
+  });
+
+  it('under the strict flag, drops later duplicate calls together with their results', () => {
     const anomalies: ProjectionAnomaly[] = [];
+    const projected = project(duplicateAcrossSteps, {
+      dedupeDuplicateToolCalls: true,
+      dropOrphanResults: true,
+      onAnomaly: (anomaly) => anomalies.push(anomaly),
+    });
+    const assistants = projected.filter(
+      (message) => message.role === 'assistant' && message.toolCalls.length > 0,
+    );
+    expect(assistants[0]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_a']);
+    expect(assistants[1]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_b']);
+    const toolMessages = projected.filter((message) => message.role === 'tool');
+    expect(toolMessages.map((message) => message.toolCallId)).toEqual(['call_a', 'call_b']);
+    expect(textOf(toolMessages[0])).toBe('first result');
+    expect(anomalies).toContainEqual({
+      kind: 'duplicate_tool_call_dropped',
+      toolCallId: 'call_a',
+    });
+    expect(anomalies).toContainEqual({
+      kind: 'duplicate_tool_result_dropped',
+      toolCallId: 'call_a',
+    });
+    expect(everyToolUseImmediatelyAnswered(projected)).toBe(true);
+  });
+
+  it('under the strict flag, drops a duplicate call id within one assistant message', () => {
     const projected = project(
       [
         user('u1'),
@@ -558,41 +606,39 @@ describe('project duplicate tool_use ids', () => {
         tool('call_dup', 'result'),
         user('u2'),
       ],
-      { dropOrphanResults: true, onAnomaly: (anomaly) => anomalies.push(anomaly) },
+      { dedupeDuplicateToolCalls: true, dropOrphanResults: true },
     );
     const assistantMessage = projected.find((message) => message.role === 'assistant');
     expect(assistantMessage?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_dup']);
-    expect(anomalies).toContainEqual({
-      kind: 'duplicate_tool_call_dropped',
-      toolCallId: 'call_dup',
-    });
     expect(everyToolUseImmediatelyAnswered(projected)).toBe(true);
   });
 
-  it('drops a tool call id repeated across assistant messages, keeping the first', () => {
+  it("under the strict flag, reattaches a later duplicate's result when the first call has none", () => {
     const projected = project(
       [
         user('u1'),
-        assistant(['call_a'], 'first'),
-        tool('call_a'),
-        assistant(['call_a', 'call_b'], 'second'),
-        tool('call_b'),
+        assistant(['call_a'], 'first attempt'),
+        assistant(['call_a'], 'second attempt'),
+        tool('call_a', 'late result'),
         user('u2'),
       ],
-      { dropOrphanResults: true },
-    );
-    const assistants = projected.filter(
-      (message) => message.role === 'assistant' && message.toolCalls.length > 0,
+      { dedupeDuplicateToolCalls: true, dropOrphanResults: true },
     );
-    expect(assistants[0]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_a']);
-    expect(assistants[1]?.toolCalls.map((toolCall) => toolCall.id)).toEqual(['call_b']);
+    expect(projected.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+      'tool',
+      'assistant',
+      'user',
+    ]);
+    expect(textOf(projected[2])).toBe('late result');
     expect(everyToolUseImmediatelyAnswered(projected)).toBe(true);
   });
 
-  it('drops an assistant message left empty after removing duplicate tool calls', () => {
+  it('under the strict flag, drops an assistant message left empty after removing duplicates', () => {
     const projected = project(
       [user('u1'), assistant(['call_a'], 'first'), tool('call_a'), assistant(['call_a']), user('u2')],
-      { dropOrphanResults: true },
+      { dedupeDuplicateToolCalls: true, dropOrphanResults: true },
     );
     expect(projected.map((message) => message.role)).toEqual(['user', 'assistant', 'tool', 'user']);
   });
diff --git a/packages/kosong/src/errors.ts b/packages/kosong/src/errors.ts
index e35980560..cd7076d83 100644
--- a/packages/kosong/src/errors.ts
+++ b/packages/kosong/src/errors.ts
@@ -237,6 +237,11 @@ const STRUCTURAL_REQUEST_MESSAGE_PATTERNS = [
   /first message must use the .*user.* role/,
   /roles must alternate/,
   /multiple .*(?:user|assistant).* roles in a row/,
+  // Anthropic rejects a request whose assistant messages carry two `tool_use`
+  // blocks with the same id: "messages: `tool_use` ids must be unique". Seen
+  // when a provider reused a call id (e.g. per-response counter ids) earlier
+  // in the session; the strict resend dedupes the ids.
+  /tool_use[\s\S]*ids must be unique/,
 ] as const;
 
 export function isRecoverableRequestStructureError(error: unknown): boolean {
diff --git a/packages/kosong/test/errors.test.ts b/packages/kosong/test/errors.test.ts
index 47c4c3eb8..7cd925334 100644
--- a/packages/kosong/test/errors.test.ts
+++ b/packages/kosong/test/errors.test.ts
@@ -378,6 +378,14 @@ describe('isRecoverableRequestStructureError', () => {
     ).toBe(true);
   });
 
+  it('matches the Anthropic duplicate tool_use id rejection', () => {
+    expect(
+      isRecoverableRequestStructureError(
+        new APIStatusError(400, 'messages: `tool_use` ids must be unique'),
+      ),
+    ).toBe(true);
+  });
+
   it('matches empty / whitespace-only text content rejections', () => {
     expect(
       isRecoverableRequestStructureError(

From 8825edee6fcdcf001b3cd899636bc65862d792d0 Mon Sep 17 00:00:00 2001
From: Kaiyi <me@kaiyi.cool>
Date: Fri, 3 Jul 2026 16:00:21 +0800
Subject: [PATCH 5/5] feat(cli): wait for background subagents before exiting
 kimi -p

When `background.keep_alive_on_exit` is enabled, `kimi -p` now waits for
all background subagents to reach a terminal state before exiting, bounded
by `background.print_wait_ceiling_s` (default 3600s). This lets concurrent
background subagents run to completion in single-turn runs instead of being
torn down when the main agent's turn ends.
---
 .changeset/print-wait-background-subagents.md |   5 +
 apps/kimi-code/src/cli/run-prompt.ts          |  14 +-
 apps/kimi-code/test/cli/run-prompt.test.ts    |  32 ++++
 docs/en/configuration/config-files.md         |   5 +-
 docs/zh/configuration/config-files.md         |   5 +-
 packages/agent-core/src/rpc/core-api.ts       |   1 +
 packages/agent-core/src/rpc/core-impl.ts      |   4 +
 packages/agent-core/src/session/index.ts      |  75 ++++++++
 packages/agent-core/src/session/rpc.ts        |   4 +
 .../test/session/lifecycle-hooks.test.ts      | 160 ++++++++++++++++++
 packages/node-sdk/src/rpc.ts                  |   5 +
 packages/node-sdk/src/session.ts              |  12 ++
 12 files changed, 319 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/print-wait-background-subagents.md

diff --git a/.changeset/print-wait-background-subagents.md b/.changeset/print-wait-background-subagents.md
new file mode 100644
index 000000000..825356473
--- /dev/null
+++ b/.changeset/print-wait-background-subagents.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+In `kimi -p` runs, wait for background subagents to finish before exiting when `background.keep_alive_on_exit` is enabled. Set `keep_alive_on_exit = true` to let concurrent background subagents complete.
diff --git a/apps/kimi-code/src/cli/run-prompt.ts b/apps/kimi-code/src/cli/run-prompt.ts
index 6f9379259..2d2c71b2d 100644
--- a/apps/kimi-code/src/cli/run-prompt.ts
+++ b/apps/kimi-code/src/cli/run-prompt.ts
@@ -510,7 +510,19 @@ function runPromptTurn(
           return;
         case 'turn.ended':
           if (event.reason === 'completed') {
-            finish();
+            void (async () => {
+              // Flush the buffered assistant message before draining background
+              // tasks: in stream-json mode the final message is only emitted by
+              // finish(), so a long background wait would otherwise withhold the
+              // main turn's result until the drain settles.
+              outputWriter.flushAssistant();
+              try {
+                await session.waitForBackgroundTasksOnPrint();
+              } catch (error) {
+                log.warn('waitForBackgroundTasksOnPrint failed', { error });
+              }
+              finish();
+            })();
             return;
           }
           finish(new Error(formatTurnEndedFailure(event)));
diff --git a/apps/kimi-code/test/cli/run-prompt.test.ts b/apps/kimi-code/test/cli/run-prompt.test.ts
index 41673cc51..924fcdad8 100644
--- a/apps/kimi-code/test/cli/run-prompt.test.ts
+++ b/apps/kimi-code/test/cli/run-prompt.test.ts
@@ -39,6 +39,7 @@ const mocks = vi.hoisted(() => {
         handler(mainEvent({ type: 'turn.ended', turnId: 1, reason: 'completed' }));
       }
     }),
+    waitForBackgroundTasksOnPrint: vi.fn(async () => {}),
   };
 
   return {
@@ -659,6 +660,37 @@ describe('runPrompt', () => {
     );
   });
 
+  it('flushes stream-json assistant output before waiting for background tasks', async () => {
+    let releaseWait: () => void = () => {};
+    const waitGate = new Promise<void>((resolve) => {
+      releaseWait = resolve;
+    });
+    mocks.session.waitForBackgroundTasksOnPrint.mockImplementationOnce(async () => waitGate);
+
+    mocks.session.prompt.mockImplementationOnce(async () => {
+      for (const handler of mocks.eventHandlers) {
+        handler(mocks.mainEvent({ type: 'turn.started', turnId: 9, origin: { kind: 'user' } }));
+        handler(mocks.mainEvent({ type: 'assistant.delta', turnId: 9, delta: 'final answer' }));
+        handler(mocks.mainEvent({ type: 'turn.ended', turnId: 9, reason: 'completed' }));
+      }
+    });
+
+    const stdout = writer();
+    const stderr = writer();
+    const runPromise = runPrompt(opts({ outputFormat: 'stream-json' }), '1.2.3-test', {
+      stdout,
+      stderr,
+    });
+
+    // The assistant message must be flushed even while the background wait is pending.
+    await waitForAssertion(() => {
+      expect(stdout.text()).toContain('{"role":"assistant","content":"final answer"}');
+    });
+
+    releaseWait();
+    await runPromise;
+  });
+
   it('resumes a concrete session without a configured default model', async () => {
     mocks.harnessGetConfig.mockResolvedValueOnce({ providers: {}, telemetry: true });
     mocks.session.getStatus.mockResolvedValueOnce({ permission: 'manual', model: 'saved-model' });
diff --git a/docs/en/configuration/config-files.md b/docs/en/configuration/config-files.md
index 254d34b7d..0d4e57a18 100644
--- a/docs/en/configuration/config-files.md
+++ b/docs/en/configuration/config-files.md
@@ -193,10 +193,13 @@ You can also switch models temporarily without touching the config file — by s
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `max_running_tasks` | `integer` | — | Maximum number of background tasks running concurrently |
-| `keep_alive_on_exit` | `boolean` | `false` | Whether to keep still-running background tasks when the session closes. By default, Kimi Code requests that all background tasks stop before the process exits; set this to `true` only when you want tasks to outlive the session |
+| `keep_alive_on_exit` | `boolean` | `false` | Whether to keep still-running background tasks when the session closes. By default, Kimi Code requests that all background tasks stop before the process exits; set this to `true` only when you want tasks to outlive the session. In print mode (`kimi -p`), setting this to `true` also makes the process wait for all background tasks to finish before exiting, so background subagents can complete their work |
+| `print_wait_ceiling_s` | `integer` | `3600` | In print mode (`kimi -p`) with `keep_alive_on_exit = true`, the maximum number of seconds the process waits for background tasks to finish after the main agent's turn ends. Has no effect outside print mode or when `keep_alive_on_exit` is `false` |
 
 `keep_alive_on_exit` can be overridden by the `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` environment variable, which takes higher priority than `config.toml`.
 
+In print mode (`kimi -p "<prompt>"`), Kimi Code runs a single non-interactive turn and exits as soon as the main agent finishes. If you launch background tasks (for example, concurrent subagents via `Agent(run_in_background=true)`) and need them to run to completion, set `keep_alive_on_exit = true`: the process then waits for every background task to reach a terminal state before exiting, bounded by `print_wait_ceiling_s`. Without it, the single turn ending tears background tasks down with the process.
+
 <!--
 ## `experimental`
 
diff --git a/docs/zh/configuration/config-files.md b/docs/zh/configuration/config-files.md
index c02f9a123..d1c0d8166 100644
--- a/docs/zh/configuration/config-files.md
+++ b/docs/zh/configuration/config-files.md
@@ -193,10 +193,13 @@ display_name = "Kimi for Coding (custom)"
 | 字段 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `max_running_tasks` | `integer` | — | 同时运行的最大后台任务数 |
-| `keep_alive_on_exit` | `boolean` | `false` | 会话关闭时是否保留仍在运行的后台任务。默认情况下，Kimi Code 会在进程退出前请求停止所有后台任务；只有希望任务在会话结束后继续运行时才设为 `true` |
+| `keep_alive_on_exit` | `boolean` | `false` | 会话关闭时是否保留仍在运行的后台任务。默认情况下，Kimi Code 会在进程退出前请求停止所有后台任务；只有希望任务在会话结束后继续运行时才设为 `true`。在 print 模式（`kimi -p`）下，设为 `true` 还会让进程在退出前等待所有后台任务跑完，使后台子代理得以完成工作 |
+| `print_wait_ceiling_s` | `integer` | `3600` | 在 print 模式（`kimi -p`）且 `keep_alive_on_exit = true` 时，主 agent 的 turn 结束后进程等待后台任务完成的最长秒数。在非 print 模式或 `keep_alive_on_exit` 为 `false` 时无效 |
 
 `keep_alive_on_exit` 可被环境变量 `KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT` 覆盖，优先级高于配置文件。
 
+在 print 模式（`kimi -p "<prompt>"`）下，Kimi Code 只跑一个非交互的单轮 turn，主 agent 一结束就退出。如果你启动了后台任务（例如通过 `Agent(run_in_background=true)` 并发子代理）并希望它们跑完，请设置 `keep_alive_on_exit = true`：进程会在退出前等待所有后台任务进入终态，最长不超过 `print_wait_ceiling_s`。否则，单轮 turn 结束时后台任务会随进程一起被清理。
+
 <!--
 ## `experimental`
 
diff --git a/packages/agent-core/src/rpc/core-api.ts b/packages/agent-core/src/rpc/core-api.ts
index 65ed62f8f..e397ae6ee 100644
--- a/packages/agent-core/src/rpc/core-api.ts
+++ b/packages/agent-core/src/rpc/core-api.ts
@@ -431,6 +431,7 @@ export interface SessionAPI extends AgentAPIWithId {
   reconnectMcpServer: (payload: ReconnectMcpServerPayload) => void;
   generateAgentsMd: (payload: EmptyPayload) => void;
   getSessionWarnings: (payload: EmptyPayload) => readonly SessionWarning[];
+  waitForBackgroundTasksOnPrint: (payload: EmptyPayload) => void;
   addAdditionalDir: (payload: AddAdditionalDirPayload) => AddAdditionalDirResult;
 }
 
diff --git a/packages/agent-core/src/rpc/core-impl.ts b/packages/agent-core/src/rpc/core-impl.ts
index c028b6d51..dfac26eb5 100644
--- a/packages/agent-core/src/rpc/core-impl.ts
+++ b/packages/agent-core/src/rpc/core-impl.ts
@@ -791,6 +791,10 @@ export class KimiCore implements PromisableMethods<CoreAPI> {
     return this.sessionApi(sessionId).getSessionWarnings(payload);
   }
 
+  waitForBackgroundTasksOnPrint({ sessionId, ...payload }: SessionScopedPayload<EmptyPayload>): Promise<void> {
+    return this.sessionApi(sessionId).waitForBackgroundTasksOnPrint(payload);
+  }
+
   addAdditionalDir({
     sessionId,
     ...payload
diff --git a/packages/agent-core/src/session/index.ts b/packages/agent-core/src/session/index.ts
index 0506bc789..da0b9b015 100644
--- a/packages/agent-core/src/session/index.ts
+++ b/packages/agent-core/src/session/index.ts
@@ -423,6 +423,81 @@ export class Session {
     );
   }
 
+  /**
+   * Wait for all still-running background tasks (across every agent) to reach a
+   * terminal state before a `kimi -p` (print) run exits.
+   *
+   * Gated by `background.keep_alive_on_exit`: when it is not `true`, this returns
+   * immediately so print mode keeps its default single-turn semantics. The wait is
+   * bounded by `background.print_wait_ceiling_s` (default 3600s) so a wedged task
+   * cannot keep the process alive forever.
+   *
+   * Terminal notifications are suppressed for each task while we wait, so a task
+   * completing cannot `turn.steer` the (already finished) main agent into launching
+   * a new turn.
+   */
+  async waitForBackgroundTasksOnPrint(): Promise<void> {
+    const keepAliveOnExit = resolveConfigValue({
+      env: process.env,
+      envKey: BACKGROUND_KEEP_ALIVE_ON_EXIT_ENV,
+      configValue: this.options.background?.keepAliveOnExit,
+      defaultValue: false,
+      parseEnv: parseBooleanEnv,
+    });
+    if (!keepAliveOnExit) return;
+
+    const ceilingS = this.options.background?.printWaitCeilingS ?? 3600;
+    const timeoutMs = ceilingS * 1000;
+    const deadline = Date.now() + timeoutMs;
+
+    // Re-enumerate active background tasks across every agent until none remain
+    // (or the ceiling expires). A subagent may fan out new background tasks
+    // after a previous enumeration, so a single pass could return while those
+    // later tasks are still running — breaking the "every background task"
+    // guarantee. Each round waits for the newly discovered tasks, then rescans
+    // to catch anything spawned in the meantime.
+    const seen = new Set<string>();
+    const allWaiters: Promise<unknown>[] = [];
+    while (Date.now() < deadline) {
+      const batch: Promise<unknown>[] = [];
+      const suppressions: Promise<void>[] = [];
+      let activeCount = 0;
+      for (const agent of this.readyAgents()) {
+        for (const task of agent.background.list(true)) {
+          activeCount++;
+          if (seen.has(task.taskId)) continue;
+          seen.add(task.taskId);
+          // suppressTerminalNotification sets the suppressed flag synchronously
+          // when called; defer awaiting the persist until after the whole
+          // enumeration so no task can complete and fire a notification while
+          // another task's persist write is pending.
+          suppressions.push(agent.background.suppressTerminalNotification(task.taskId));
+          const remaining = Math.max(1, deadline - Date.now());
+          const waiter = agent.background.wait(task.taskId, remaining);
+          batch.push(waiter);
+          allWaiters.push(waiter);
+        }
+      }
+      if (suppressions.length > 0) {
+        await Promise.all(suppressions);
+      }
+      if (activeCount === 0 || batch.length === 0) break;
+      this.log.info('waiting for background tasks before print exit', {
+        active: activeCount,
+        new: batch.length,
+        timeoutMs,
+      });
+      await Promise.all(batch);
+    }
+    if (allWaiters.length > 0) {
+      await Promise.all(allWaiters);
+      this.log.info('background tasks settled before print exit', {
+        count: seen.size,
+        timeoutMs,
+      });
+    }
+  }
+
   async createAgent(
     config: Partial<AgentOptions>,
     options: CreateAgentOptions = {},
diff --git a/packages/agent-core/src/session/rpc.ts b/packages/agent-core/src/session/rpc.ts
index 63276f0dc..bc3be48b3 100644
--- a/packages/agent-core/src/session/rpc.ts
+++ b/packages/agent-core/src/session/rpc.ts
@@ -107,6 +107,10 @@ export class SessionAPIImpl implements PromisableMethods<SessionAPI> {
     return this.session.getSessionWarnings();
   }
 
+  waitForBackgroundTasksOnPrint(_payload: EmptyPayload): Promise<void> {
+    return this.session.waitForBackgroundTasksOnPrint();
+  }
+
   addAdditionalDir(payload: AddAdditionalDirPayload): Promise<AddAdditionalDirResult> {
     return this.session.addAdditionalDir(payload.path, payload.persist);
   }
diff --git a/packages/agent-core/test/session/lifecycle-hooks.test.ts b/packages/agent-core/test/session/lifecycle-hooks.test.ts
index 1571a1bae..38f55666c 100644
--- a/packages/agent-core/test/session/lifecycle-hooks.test.ts
+++ b/packages/agent-core/test/session/lifecycle-hooks.test.ts
@@ -219,6 +219,166 @@ describe('Session lifecycle hooks', () => {
     expect(main.background.getTask(taskId)?.status).toBe('running');
   });
 
+  it('waitForBackgroundTasksOnPrint returns immediately when keepAliveOnExit is false', async () => {
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      kaos: testKaos.withCwd(workDir),
+      id: 'session-print-wait-disabled',
+      homedir: sessionDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      background: { keepAliveOnExit: false },
+    });
+    const agent = await session.createMain();
+    const { proc, killSpy } = pendingProcess();
+    const taskId = agent.background.registerTask(
+      new ProcessBackgroundTask(proc, 'sleep 60', 'no wait'),
+    );
+
+    await session.waitForBackgroundTasksOnPrint();
+
+    expect(killSpy).not.toHaveBeenCalled();
+    expect(agent.background.getTask(taskId)?.status).toBe('running');
+    await session.close();
+  });
+
+  it('waitForBackgroundTasksOnPrint waits for background tasks to finish when keepAliveOnExit is true', async () => {
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      kaos: testKaos.withCwd(workDir),
+      id: 'session-print-wait',
+      homedir: sessionDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      background: { keepAliveOnExit: true },
+    });
+    const agent = await session.createMain();
+    const { proc } = pendingProcess(0);
+    const taskId = agent.background.registerTask(
+      new ProcessBackgroundTask(proc, 'sleep 60', 'wait for me'),
+    );
+
+    let settled = false;
+    const waitPromise = session.waitForBackgroundTasksOnPrint().then(() => {
+      settled = true;
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(settled).toBe(false);
+
+    await proc.kill('SIGTERM');
+    await waitPromise;
+    expect(settled).toBe(true);
+    expect(agent.background.getTask(taskId)?.status).toBe('completed');
+    await session.close();
+  });
+
+  it('waitForBackgroundTasksOnPrint times out after printWaitCeilingS', async () => {
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      kaos: testKaos.withCwd(workDir),
+      id: 'session-print-wait-timeout',
+      homedir: sessionDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      background: { keepAliveOnExit: true, printWaitCeilingS: 1 },
+    });
+    const agent = await session.createMain();
+    const { proc } = pendingProcess();
+    const taskId = agent.background.registerTask(
+      new ProcessBackgroundTask(proc, 'sleep 60', 'times out'),
+    );
+
+    await session.waitForBackgroundTasksOnPrint();
+
+    expect(agent.background.getTask(taskId)?.status).toBe('running');
+    await session.close();
+  });
+
+  it('waitForBackgroundTasksOnPrint waits for tasks spawned after the first enumeration', async () => {
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      kaos: testKaos.withCwd(workDir),
+      id: 'session-print-wait-fanout',
+      homedir: sessionDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      background: { keepAliveOnExit: true },
+    });
+    const agent = await session.createMain();
+    const first = pendingProcess(0);
+    const firstTaskId = agent.background.registerTask(
+      new ProcessBackgroundTask(first.proc, 'sleep 60', 'first'),
+    );
+
+    let settled = false;
+    const waitPromise = session.waitForBackgroundTasksOnPrint().then(() => {
+      settled = true;
+    });
+
+    // Let the first enumeration run and suspend on the first task.
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(settled).toBe(false);
+
+    // Fan out a second background task after the first enumeration.
+    const second = pendingProcess(0);
+    const secondTaskId = agent.background.registerTask(
+      new ProcessBackgroundTask(second.proc, 'sleep 60', 'second'),
+    );
+
+    // Finish the first task; the wait must not settle while the second is running.
+    await first.proc.kill('SIGTERM');
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(settled).toBe(false);
+
+    // Finish the second task; the wait should now settle.
+    await second.proc.kill('SIGTERM');
+    await waitPromise;
+    expect(settled).toBe(true);
+    expect(agent.background.getTask(firstTaskId)?.status).toBe('completed');
+    expect(agent.background.getTask(secondTaskId)?.status).toBe('completed');
+    await session.close();
+  });
+
+  it('suppresses notifications for every active task before awaiting any of them', async () => {
+    const { sessionDir, workDir } = await hookFixture();
+    const session = new Session({
+      kaos: testKaos.withCwd(workDir),
+      id: 'session-print-wait-suppress-race',
+      homedir: sessionDir,
+      rpc: createSessionRpc(),
+      skills: { explicitDirs: [join(workDir, 'missing-skills')] },
+      background: { keepAliveOnExit: true },
+    });
+    const agent = await session.createMain();
+    const steerSpy = vi.spyOn(agent.turn, 'steer');
+
+    // Detached tasks fire a completion notification unless suppressed.
+    const first = pendingProcess(0);
+    agent.background.registerTask(new ProcessBackgroundTask(first.proc, 'sleep 60', 'first'), {
+      detached: true,
+    });
+    const second = pendingProcess(0);
+    agent.background.registerTask(
+      new ProcessBackgroundTask(second.proc, 'sleep 60', 'second'),
+      { detached: true },
+    );
+
+    const waitPromise = session.waitForBackgroundTasksOnPrint();
+
+    // Let the synchronous enumeration run so both tasks get suppressed.
+    await new Promise((resolve) => setImmediate(resolve));
+
+    // Complete both tasks after suppression but before the wait settles.
+    await first.proc.kill('SIGTERM');
+    await second.proc.kill('SIGTERM');
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(steerSpy).not.toHaveBeenCalled();
+    await waitPromise;
+    await session.close();
+  });
+
   it('lets the environment override config when deciding background task cleanup', async () => {
     vi.stubEnv('KIMI_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT', '0');
     const { sessionDir, workDir } = await hookFixture();
diff --git a/packages/node-sdk/src/rpc.ts b/packages/node-sdk/src/rpc.ts
index 18a431d8c..86a67c60b 100644
--- a/packages/node-sdk/src/rpc.ts
+++ b/packages/node-sdk/src/rpc.ts
@@ -542,6 +542,11 @@ export abstract class SDKRpcClientBase {
     });
   }
 
+  async waitForBackgroundTasksOnPrint(input: SessionIdRpcInput): Promise<void> {
+    const rpc = await this.getRpc();
+    return rpc.waitForBackgroundTasksOnPrint({ sessionId: input.sessionId });
+  }
+
   async createGoal(input: SessionIdRpcInput & CreateGoalInput): Promise<GoalSnapshot> {
     const rpc = await this.getRpc();
     return rpc.createGoal({
diff --git a/packages/node-sdk/src/session.ts b/packages/node-sdk/src/session.ts
index eab063a02..3e28ad394 100644
--- a/packages/node-sdk/src/session.ts
+++ b/packages/node-sdk/src/session.ts
@@ -377,6 +377,18 @@ export class Session {
     });
   }
 
+  /**
+   * Block until every still-running background task (across all agents in this
+   * session) reaches a terminal state. Used by `kimi -p` after the main agent's
+   * turn finishes when `background.keep_alive_on_exit` is `true`, so background
+   * subagents get a chance to complete before the process exits. No-op when
+   * `keep_alive_on_exit` is not enabled. Bounded by `background.print_wait_ceiling_s`.
+   */
+  async waitForBackgroundTasksOnPrint(): Promise<void> {
+    this.ensureOpen();
+    await this.rpc.waitForBackgroundTasksOnPrint({ sessionId: this.id });
+  }
+
   // --- Goal lifecycle ---------------------------------------------------
   // Deterministic user/host control surface. There is intentionally no
   // `updateGoal`: the goal's terminal status is decided by the model via the