feat(agent-core-v2): add a handoff step after forced stops and report subagent stop reasons

.changeset/drop-subagent-summary-bounce.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Subagent final messages are no longer bounced back for expansion when they are under 200 characters.

packages/agent-core-v2/docs/state-manifest.d.ts

@@ -27,7 +27,7 @@
 // references become '(circular)', and class instances collapse to a '(ClassName)'
 // marker — the wire shape of an entry is the JSON projection of the type here.
 //
-// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 82 keys)
+// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 83 keys)
 //   App
 //   Workspace
 //     workspaceDirs.ephemeralDirs          src/workspace/workspaceDirs/workspaceDirsService.ts
@@ -116,6 +116,7 @@
 //     toolDedupe.callKeyByCallId                      src/agent/toolDedupe/toolDedupeService.ts
 //     toolDedupe.consecutiveCount                     src/agent/toolDedupe/toolDedupeService.ts
 //     toolDedupe.consecutiveKey                       src/agent/toolDedupe/toolDedupeService.ts
+//     toolDedupe.handoffPhase                         src/agent/toolDedupe/toolDedupeService.ts
 //     toolDedupe.originalCallIndex                    src/agent/toolDedupe/toolDedupeService.ts
 //     toolDedupe.stepCalls                            src/agent/toolDedupe/toolDedupeService.ts
 //     toolDedupe.syntheticCallIds                     src/agent/toolDedupe/toolDedupeService.ts
@@ -1379,6 +1380,7 @@ export interface AgentStateSnapshot {
     readonly parentToolCallId?: string;
     readonly model?: string;
     readonly thinkingEffort?: string;
+    readonly stopCode?: string;
     readonly taskId: string;
     readonly description: string;
     readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
@@ -1430,6 +1432,7 @@ export interface AgentStateSnapshot {
     readonly parentToolCallId?: string;
     readonly model?: string;
     readonly thinkingEffort?: string;
+    readonly stopCode?: string;
     readonly taskId: string;
     readonly description: string;
     readonly status: /* AgentTaskStatus — packages/agent-core-v2/src/agent/task/types.ts */ 'completed' | 'failed' | 'running' | 'timed_out' | 'killed' | 'lost';
@@ -1466,6 +1469,7 @@ export interface AgentStateSnapshot {
   'toolDedupe.callKeyByCallId': Map<string, string>;
   'toolDedupe.consecutiveCount': number;
   'toolDedupe.consecutiveKey': string | null;
+  'toolDedupe.handoffPhase': /* HandoffPhase — packages/agent-core-v2/src/agent/toolDedupe/toolDedupeService.ts */ 'idle' | 'active' | 'pending' | 'done';
   'toolDedupe.originalCallIndex': Map<string, number>;
   'toolDedupe.stepCalls': string[];
   'toolDedupe.syntheticCallIds': Set<string>;

packages/agent-core-v2/docs/wire-manifest.d.ts

@@ -854,6 +854,7 @@ interface TurnEndedPayload {
     };
   };
   durationMs?: number;
+  stopReason?: string;
 }
 
 /**

packages/agent-core-v2/src/agent/loop/handoffStep.ts

@@ -0,0 +1,24 @@
+import { ContinuationStepRequest } from './stepRequest';
+
+export const HANDOFF_STEP_KIND = 'handoff';
+
+export interface HandoffStepObserver {
+  onMaterialize(): void;
+  onAbort(): void;
+}
+
+export class HandoffStepRequest extends ContinuationStepRequest {
+  constructor(private readonly observer: HandoffStepObserver) {
+    super({ kind: HANDOFF_STEP_KIND });
+  }
+
+  override onWillMaterialize(): void {
+    this.observer.onMaterialize();
+  }
+
+  override abort(): boolean {
+    const aborted = super.abort();
+    if (aborted) this.observer.onAbort();
+    return aborted;
+  }
+}

packages/agent-core-v2/src/agent/loop/loop.ts

@@ -75,6 +75,7 @@ export type LoopRunResult =
       readonly type: 'completed';
       readonly steps: number;
       readonly truncated: boolean;
+      readonly stopReason?: string;
     }
   | {
       readonly type: 'failed';

packages/agent-core-v2/src/agent/loop/loopService.ts

@@ -56,6 +56,7 @@ import {
   type TurnSeed,
 } from './stepRequest';
 import { StepRequestQueue, type StepRequestBatch } from './stepRequestQueue';
+import { HANDOFF_STEP_KIND } from './handoffStep';
 import {
   AssistantDelta,
   isDisplayablePromptOrigin,
@@ -537,6 +538,7 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
             error,
             durationMs,
             interruptReason,
+            stopReason: result.type === 'completed' ? result.stopReason : undefined,
           }),
         );
         if (error !== undefined) {
@@ -675,24 +677,37 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
       queue: job?.queue ?? this.standaloneStepQueue,
       steps: 0,
       lastStopReason: undefined,
+      forcedStopReason: undefined,
       current: undefined,
     };
   }
 
+  private completedResult(runtime: LoopRuntime): LoopRunResult {
+    const truncated = runtime.lastStopReason === 'truncated';
+    if (runtime.forcedStopReason === undefined) {
+      return { type: 'completed', steps: runtime.steps, truncated };
+    }
+    return {
+      type: 'completed',
+      steps: runtime.steps,
+      truncated,
+      stopReason: runtime.forcedStopReason,
+    };
+  }
+
   private beginLoopStep(runtime: LoopRuntime): BeginStepResult {
     runtime.current = undefined;
     runtime.turnSignal.throwIfAborted();
     if (!runtime.queue.hasPendingRequests()) {
-      return {
-        result: {
-          type: 'completed',
-          steps: runtime.steps,
-          truncated: runtime.lastStopReason === 'truncated',
-        },
-      };
+      return { result: this.completedResult(runtime) };
     }
     const maxSteps = this.config.get<LoopControl>(LOOP_CONTROL_SECTION)?.maxStepsPerTurn;
-    if (maxSteps !== undefined && maxSteps > 0 && runtime.steps >= maxSteps) {
+    if (
+      maxSteps !== undefined &&
+      maxSteps > 0 &&
+      runtime.steps >= maxSteps &&
+      runtime.queue.peekDriverKind() !== HANDOFF_STEP_KIND
+    ) {
       throw createMaxStepsExceededError(maxSteps);
     }
     const batch = runtime.queue.takeNextBatch()!;
@@ -727,14 +742,17 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
     }
     runtime.current = undefined;
     runtime.lastStopReason = result.stopReason;
+    if (result.stopTurnReason !== undefined && runtime.forcedStopReason === undefined) {
+      runtime.forcedStopReason = result.stopTurnReason;
+    }
     if (result.stopReason === 'filtered') {
       throw new Error2(ErrorCodes.PROVIDER_FILTERED, 'Provider safety policy blocked the response.', {
         name: 'ProviderFilteredError',
         details: { finishReason: 'filtered' },
       });
     }
     if (!result.hookStopTurn) return undefined;
-    return { type: 'completed', steps: runtime.steps, truncated: result.stopReason === 'truncated' };
+    return this.completedResult(runtime);
   }
 
   private async handleLoopStepError(
@@ -861,7 +879,7 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
       }
       this.lastRequestTraceId = request.trace.traceId;
       this.appendResponseContent(turnId, currentStep, stepUuid, response);
-      const finishReason = await this.executeStepTools(
+      const { finishReason, stopTurnReason } = await this.executeStepTools(
         turnId,
         signal,
         currentStep,
@@ -879,7 +897,7 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
         response.usage,
         finishReason,
       );
-      return { stopReason: finishReason, hookStopTurn };
+      return { stopReason: finishReason, hookStopTurn, stopTurnReason };
     } catch (error) {
       if (!stepEndAppended) {
         this.context.appendLoopEvent({
@@ -968,13 +986,14 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
     stepUuid: string,
     response: AgentLLMRequestFinish,
     trace: LLMRequestTrace,
-  ): Promise<FinishReason> {
+  ): Promise<StepToolsOutcome> {
     let finishReason = response.providerFinishReason ?? 'completed';
     if (response.message.toolCalls.length === 0) {
-      return finishReason === 'tool_calls' ? 'other' : finishReason;
+      return { finishReason: finishReason === 'tool_calls' ? 'other' : finishReason };
     }
     const toolCallUuids = new Map<string, string>();
     let stopTurn = false;
+    let stopTurnReason: string | undefined;
     for await (const toolResult of this.toolExecutor.execute(response.message.toolCalls, {
       signal,
       turnId,
@@ -1003,10 +1022,13 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
         toolCallId: toolResult.toolCallId,
         result: { output: result.output, isError: result.isError, note: result.note },
       });
-      if (result.stopTurn === true) stopTurn = true;
+      if (result.stopTurn === true) {
+        stopTurn = true;
+        stopTurnReason ??= result.stopTurnReason;
+      }
     }
     finishReason = stopTurn ? 'completed' : 'tool_calls';
-    return finishReason;
+    return { finishReason, stopTurnReason };
   }
 
   private finishStep(
@@ -1239,6 +1261,7 @@ interface LoopRuntime {
   readonly queue: StepRequestQueue;
   steps: number;
   lastStopReason: FinishReason | undefined;
+  forcedStopReason: string | undefined;
   current: StepRuntime | undefined;
 }
 
@@ -1277,6 +1300,12 @@ function interruptReasonFor(
 type StepExecutionResult = {
   readonly stopReason: FinishReason;
   readonly hookStopTurn: boolean;
+  readonly stopTurnReason?: string;
+};
+
+type StepToolsOutcome = {
+  readonly finishReason: FinishReason;
+  readonly stopTurnReason?: string;
 };
 
 type LoopErrorDisposition =

packages/agent-core-v2/src/agent/loop/stepRequestQueue.ts

@@ -20,6 +20,12 @@ export class StepRequestQueue {
     return this.items.some((item) => !item.aborted);
   }
 
+  peekDriverKind(): string | undefined {
+    this.discardAborted();
+    const driver = this.items.find((item) => !item.mergeable) ?? this.items[0];
+    return driver?.kind;
+  }
+
   takeNextBatch(): StepRequestBatch | undefined {
     this.discardAborted();
     if (this.items.length === 0) return undefined;

packages/agent-core-v2/src/agent/loop/turnOps.ts

@@ -91,6 +91,7 @@ const turnEndedSchema = z.object({
   reason: z.enum(['completed', 'cancelled', 'failed', 'blocked']),
   error: z.custom<KimiErrorPayload>().optional(),
   durationMs: z.number().optional(),
+  stopReason: z.string().optional(),
 });
 
 export interface TurnEndedPayload {
@@ -100,6 +101,7 @@ export interface TurnEndedPayload {
   readonly error?: KimiErrorPayload;
   readonly durationMs?: number;
   readonly interruptReason?: TurnInterruptReason;
+  readonly stopReason?: string;
 }
 
 export class TurnEnded extends AgentEvent2<TurnEndedPayload> {
@@ -117,6 +119,7 @@ export class TurnEnded extends AgentEvent2<TurnEndedPayload> {
     };
     if (this.error !== undefined) record['error'] = this.error;
     if (this.durationMs !== undefined) record['durationMs'] = this.durationMs;
+    if (this.stopReason !== undefined) record['stopReason'] = this.stopReason;
     record['time'] = this.time;
     return record as SerializedEvent2;
   }

packages/agent-core-v2/src/agent/toolDedupe/toolDedupe.ts

@@ -15,6 +15,8 @@ export interface ToolDedupeErrorResult extends ExecutableToolErrorResult {
 
 export type ToolDedupeResult = ToolDedupeSuccessResult | ToolDedupeErrorResult;
 
+export const REPEAT_BREAKER_STOP_REASON = 'repeat_breaker';
+
 export interface IAgentToolDedupeService {
   readonly _serviceBrand: undefined;
 }